feat(wrangler): Add support for examples in --help (#6513)

This commit enables yargs `example` support in wrangler
(see https://yargs.js.org/docs/#api-reference-examplecmd1-desc1-cmd2-desc2),
and adds one for `vectorize query`.

packages/wrangler/src/__tests__/vectorize/vectorize.test.ts

@@ -142,6 +142,58 @@ describe("vectorize help", () => {
 				--------------------"
 			`);
 	});
+
+	it("should show help when the query command is passed without an argument", async () => {
+		await expect(() => runWrangler("vectorize query")).rejects.toThrow(
+			"Not enough non-option arguments: got 0, need at least 1"
+		);
+
+		expect(std.err).toMatchInlineSnapshot(`
+			"X [ERROR] Not enough non-option arguments: got 0, need at least 1
+
+			"
+		`);
+		expect(std.out).toMatchInlineSnapshot(`
+			"
+			wrangler vectorize query <name>
+
+			Query a Vectorize index
+
+			POSITIONALS
+			  name  The name of the Vectorize index  [string] [required]
+
+			GLOBAL FLAGS
+			  -j, --experimental-json-config  Experimental: support wrangler.json  [boolean]
+			  -c, --config                    Path to .toml configuration file  [string]
+			  -e, --env                       Environment to use for operations and .env files  [string]
+			  -h, --help                      Show help  [boolean]
+			  -v, --version                   Show version number  [boolean]
+
+			OPTIONS
+			      --vector           Vector to query the Vectorize Index  [array] [required]
+			      --top-k            The number of results (nearest neighbors) to return  [number] [default: 5]
+			      --return-values    Specify if the vector values should be included in the results  [boolean] [default: false]
+			      --return-metadata  Specify if the vector metadata should be included in the results  [string] [choices: \\"all\\", \\"indexed\\", \\"none\\"] [default: \\"none\\"]
+			      --namespace        Filter the query results based on this namespace  [string]
+			      --filter           Filter the query results based on this metadata filter.  [string]
+
+			EXAMPLES
+			  ❯❯ wrangler vectorize query --vector 1 2 3 0.5 1.25 6
+			     Query the Vectorize Index by vector. To read from a json file that contains data in the format [1, 2, 3], you could use a command like
+			     \`wrangler vectorize query --vector $(jq -r '.[]' data.json | xargs)\`
+
+			  ❯❯ wrangler vectorize query --filter '{ 'p1': 'abc', 'p2': { '$ne': true }, 'p3': 10, 'p4': false, 'nested.p5': 'abcd' }'
+			     Filter the query results.
+
+			--------------------
+			📣 Vectorize is currently in open beta
+			📣 Please use the '--deprecated-v1' flag to create, get, list, delete and insert vectors into legacy Vectorize indexes
+			📣 See the Vectorize docs for how to get started and known issues: https://developers.cloudflare.com/vectorize
+			📣 Please report any bugs to https://github.com/cloudflare/workers-sdk/issues/new/choose
+			📣 To give feedback, visit https://discord.cloudflare.com/
+			--------------------"
+		`);
+	});
 });
 
 describe("vectorize commands", () => {

packages/wrangler/src/index.ts

@@ -277,6 +277,7 @@ export function createCLIParser(argv: string[]) {
 		"Commands:": `${chalk.bold("COMMANDS")}`,
 		"Options:": `${chalk.bold("OPTIONS")}`,
 		"Positionals:": `${chalk.bold("POSITIONALS")}`,
+		"Examples:": `${chalk.bold("EXAMPLES")}`,
 	});
 	wrangler.group(
 		["experimental-json-config", "config", "env", "help", "version"],

packages/wrangler/src/vectorize/query.ts

@@ -21,14 +21,13 @@ export function options(yargs: CommonYargsArgv) {
 		.positional("name", {
 			type: "string",
 			demandOption: true,
-			description: "The name of the Vectorize index.",
+			description: "The name of the Vectorize index",
 		})
 		.options({
 			vector: {
 				type: "array",
 				demandOption: true,
-				describe:
-					"Vector to query the Vectorize Index. Example: `--vector 1 2 3 0.5 1.25 6`. To read from a json file that contains data in the format [1, 2, 3], you could use a command like `--vector $(jq -r '.[]' data.json | xargs)`",
+				describe: "Vector to query the Vectorize Index",
 				coerce: (arg: unknown[]) =>
 					arg
 						.map((value) =>
@@ -42,29 +41,28 @@ export function options(yargs: CommonYargsArgv) {
 			"top-k": {
 				type: "number",
 				default: 5,
-				describe: "The number of results (nearest neighbors) to return.",
+				describe: "The number of results (nearest neighbors) to return",
 			},
 			"return-values": {
 				type: "boolean",
 				default: false,
 				describe:
-					"Specify if the vector values should be included in the results.",
+					"Specify if the vector values should be included in the results",
 			},
 			"return-metadata": {
 				type: "string",
 				choices: ["all", "indexed", "none"],
 				default: "none",
 				describe:
-					"Specify if the vector metadata should be included in the results. Should be either 'all', 'indexed' or 'none'",
+					"Specify if the vector metadata should be included in the results",
 			},
 			namespace: {
 				type: "string",
 				describe: "Filter the query results based on this namespace",
 			},
 			filter: {
 				type: "string",
-				describe:
-					"Filter the query results based on this metadata filter. Example: `--filter '{ 'p1': 'abc', 'p2': { '$ne': true }, 'p3': 10, 'p4': false, 'nested.p5': 'abcd' }'`",
+				describe: "Filter the query results based on this metadata filter.",
 				coerce: (jsonStr: string): VectorizeQueryOptions["filter"] => {
 					try {
 						return JSON.parse(jsonStr);
@@ -76,6 +74,17 @@ export function options(yargs: CommonYargsArgv) {
 				},
 			},
 		})
+		.example([
+			[
+				`❯❯ wrangler vectorize query --vector 1 2 3 0.5 1.25 6\n` +
+					"   Query the Vectorize Index by vector. To read from a json file that contains data in the format [1, 2, 3], you could use a command like\n" +
+					"   `wrangler vectorize query --vector $(jq -r '.[]' data.json | xargs)`\n",
+			],
+			[
+				"❯❯ wrangler vectorize query --filter '{ 'p1': 'abc', 'p2': { '$ne': true }, 'p3': 10, 'p4': false, 'nested.p5': 'abcd' }'\n" +
+					"   Filter the query results.",
+			],
+		])
 		.epilogue(vectorizeBetaWarning);
 }