Use a --query flag for doc search instead of a positional arg

Per the CLI design guidelines: flags make intent explicit, don't rely
on order, and are easier to evolve. Regenerated manifest + README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Nelson Wittwer

packages/cli/README.md

@@ -39,7 +39,7 @@
 * [`shopify config autoupgrade off`](#shopify-config-autoupgrade-off)
 * [`shopify config autoupgrade on`](#shopify-config-autoupgrade-on)
 * [`shopify config autoupgrade status`](#shopify-config-autoupgrade-status)
-* [`shopify doc search <query>`](#shopify-doc-search-query)
+* [`shopify doc search`](#shopify-doc-search)
 * [`shopify help [command] [flags]`](#shopify-help-command-flags)
 * [`shopify hydrogen build`](#shopify-hydrogen-build)
 * [`shopify hydrogen check RESOURCE`](#shopify-hydrogen-check-resource)
@@ -1214,23 +1214,21 @@ DESCRIPTION
   Run `shopify config autoupgrade on` or `shopify config autoupgrade off` to configure it.
 ```
 
-## `shopify doc search <query>`
+## `shopify doc search`
 
 Query the shopify.dev vector store and print the most relevant documentation chunks as JSON. Best for programmatic discovery — surfacing the relevant pieces of documentation for a topic, rather than retrieving a whole document. To download a full document verbatim, use `doc fetch`.
 
 ```
 USAGE
-  $ shopify doc search <query>
-
-ARGUMENTS
-  QUERY  The search query.
+  $ shopify doc search --query <value> [--api-name <value>] [--api-version <value>] [--no-color] [--verbose]
 
 FLAGS
   --api-name=<value>     [env: SHOPIFY_FLAG_API_NAME] Limit results to a specific API (for example: admin, storefront,
                          hydrogen, functions). Unrecognized values are ignored.
   --api-version=<value>  [env: SHOPIFY_FLAG_API_VERSION] Limit results to a specific API version (for example: 2025-10,
                          latest, current).
   --no-color             [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
+  --query=<value>        (required) [env: SHOPIFY_FLAG_QUERY] The search query.
   --verbose              [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
 
 DESCRIPTION
@@ -1240,9 +1238,9 @@ DESCRIPTION
 
 EXAMPLES
   # search shopify.dev for a topic
-      shopify doc search "subscribe to webhooks"
+      shopify doc search --query "subscribe to webhooks"
       # narrow the search to a specific API and version
-      shopify doc search "create a product" --api-name admin --api-version latest
+      shopify doc search --query "create a product" --api-name admin --api-version latest
 ```
 
 ## `shopify help [command] [flags]`

packages/cli/oclif.manifest.json

@@ -3439,16 +3439,11 @@
       "aliases": [
       ],
       "args": {
-        "query": {
-          "description": "The search query.",
-          "name": "query",
-          "required": true
-        }
       },
       "description": "Query the shopify.dev vector store and print the most relevant documentation chunks as JSON. Best for programmatic discovery — surfacing the relevant pieces of documentation for a topic, rather than retrieving a whole document. To download a full document verbatim, use `doc fetch`.",
       "enableJsonFlag": false,
       "examples": [
-        "# search shopify.dev for a topic\n    shopify doc search \"subscribe to webhooks\"\n\n    # narrow the search to a specific API and version\n    shopify doc search \"create a product\" --api-name admin --api-version latest\n    "
+        "# search shopify.dev for a topic\n    shopify doc search --query \"subscribe to webhooks\"\n\n    # narrow the search to a specific API and version\n    shopify doc search --query \"create a product\" --api-name admin --api-version latest\n    "
       ],
       "flags": {
         "api-name": {
@@ -3475,6 +3470,15 @@
           "name": "no-color",
           "type": "boolean"
         },
+        "query": {
+          "description": "The search query.",
+          "env": "SHOPIFY_FLAG_QUERY",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "query",
+          "required": true,
+          "type": "option"
+        },
         "verbose": {
           "allowNo": false,
           "description": "Increase the verbosity of the output.",
@@ -3491,8 +3495,7 @@
       "pluginAlias": "@shopify/cli",
       "pluginName": "@shopify/cli",
       "pluginType": "core",
-      "strict": true,
-      "usage": "doc search <query>"
+      "strict": true
     },
     "docs:generate": {
       "aliases": [

packages/cli/src/cli/commands/doc/search.ts

@@ -1,33 +1,28 @@
 import {docSearchService} from '../../services/commands/doc/search.js'
 import Command from '@shopify/cli-kit/node/base-command'
 import {globalFlags} from '@shopify/cli-kit/node/cli'
-import {Args, Flags} from '@oclif/core'
+import {Flags} from '@oclif/core'
 
 export default class DocSearch extends Command {
   static description =
     'Query the shopify.dev vector store and print the most relevant documentation chunks as JSON. Best for programmatic discovery — surfacing the relevant pieces of documentation for a topic, rather than retrieving a whole document. To download a full document verbatim, use `doc fetch`.'
 
-  static usage = `doc search <query>`
-
   static examples = [
     `# search shopify.dev for a topic
-    shopify doc search "subscribe to webhooks"
+    shopify doc search --query "subscribe to webhooks"
 
     # narrow the search to a specific API and version
-    shopify doc search "create a product" --api-name admin --api-version latest
+    shopify doc search --query "create a product" --api-name admin --api-version latest
     `,
   ]
 
-  static args = {
-    query: Args.string({
-      name: 'query',
-      required: true,
-      description: 'The search query.',
-    }),
-  }
-
   static flags = {
     ...globalFlags,
+    query: Flags.string({
+      description: 'The search query.',
+      env: 'SHOPIFY_FLAG_QUERY',
+      required: true,
+    }),
     'api-name': Flags.string({
       description:
         'Limit results to a specific API (for example: admin, storefront, hydrogen, functions). Unrecognized values are ignored.',
@@ -40,7 +35,7 @@ export default class DocSearch extends Command {
   }
 
   async run(): Promise<void> {
-    const {args, flags} = await this.parse(DocSearch)
-    await docSearchService(args.query, flags['api-name'], flags['api-version'])
+    const {flags} = await this.parse(DocSearch)
+    await docSearchService(flags.query, flags['api-name'], flags['api-version'])
   }
 }