Deprecate and fix search

.changeset/deprecate-and-fix-search.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli': patch
+---
+
+Fix and deprecate `shopify search`. It now opens `https://shopify.dev/docs?search=<query>` directly (previously it opened a URL that 301-redirected there). The command is also marked deprecated in favor of `doc search`, which returns matching documentation as JSON for programmatic and agent-driven use. `search` keeps its existing browser behavior, so existing usage is unaffected.

packages/cli/README.md

@@ -2083,14 +2083,16 @@ DESCRIPTION
 
 ## `shopify search [query]`
 
-Starts a search on shopify.dev.
+Opens shopify.dev in your browser to search the documentation using the on-site search. Intended for interactive, human use. Deprecated: if you are an agent or need results programmatically, use `doc search` instead, which returns the matching documentation as JSON.
 
 ```
 USAGE
   $ shopify search [query]
 
 DESCRIPTION
-  Starts a search on shopify.dev.
+  Opens shopify.dev in your browser to search the documentation using the on-site search. Intended for interactive,
+  human use. Deprecated: if you are an agent or need results programmatically, use `doc search` instead, which returns
+  the matching documentation as JSON.
 
 EXAMPLES
   # open the search modal on Shopify.dev

packages/cli/oclif.manifest.json

@@ -5652,7 +5652,10 @@
           "name": "query"
         }
       },
-      "description": "Starts a search on shopify.dev.",
+      "deprecationOptions": {
+        "to": "doc search"
+      },
+      "description": "Opens shopify.dev in your browser to search the documentation using the on-site search. Intended for interactive, human use. Deprecated: if you are an agent or need results programmatically, use `doc search` instead, which returns the matching documentation as JSON.",
       "enableJsonFlag": false,
       "examples": [
         "# open the search modal on Shopify.dev\n    shopify search\n\n    # search for a term on Shopify.dev\n    shopify search <query>\n\n    # search for a phrase on Shopify.dev\n    shopify search \"<a search query separated by spaces>\"\n    "
@@ -5666,6 +5669,7 @@
       "pluginAlias": "@shopify/cli",
       "pluginName": "@shopify/cli",
       "pluginType": "core",
+      "state": "deprecated",
       "strict": true,
       "usage": "search [query]"
     },

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

@@ -3,7 +3,14 @@ import Command from '@shopify/cli-kit/node/base-command'
 import {Args} from '@oclif/core'
 
 export default class Search extends Command {
-  static description = 'Starts a search on shopify.dev.'
+  static description =
+    'Opens shopify.dev in your browser to search the documentation using the on-site search. Intended for interactive, human use. Deprecated: if you are an agent or need results programmatically, use `doc search` instead, which returns the matching documentation as JSON.'
+
+  // Deprecated in favor of `doc search`, which returns JSON for programmatic use.
+  // The browser behavior is intentionally preserved so existing usage doesn't break;
+  // oclif emits a runtime deprecation warning pointing to `doc search`.
+  static state = 'deprecated'
+  static deprecationOptions = {to: 'doc search'}
 
   static usage = `search [query]`
 

packages/cli/src/cli/services/commands/search.test.ts

@@ -8,12 +8,12 @@ describe('searchService', () => {
   test('the right URL is open in the system when a query is passed', async () => {
     await searchService('deploy app')
 
-    expect(openURL).toBeCalledWith('https://shopify.dev?search=deploy+app')
+    expect(openURL).toBeCalledWith('https://shopify.dev/docs?search=deploy+app')
   })
 
   test('the right URL is open in the system when a query is not passed', async () => {
     await searchService()
 
-    expect(openURL).toBeCalledWith('https://shopify.dev?search=')
+    expect(openURL).toBeCalledWith('https://shopify.dev/docs?search=')
   })
 })

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

@@ -3,5 +3,5 @@ import {openURL} from '@shopify/cli-kit/node/system'
 export async function searchService(query?: string) {
   const searchParams = new URLSearchParams()
   searchParams.append('search', query ?? '')
-  await openURL(`https://shopify.dev?${searchParams.toString()}`)
+  await openURL(`https://shopify.dev/docs?${searchParams.toString()}`)
 }

packages/e2e/data/snapshots/commands.txt

@@ -91,7 +91,6 @@
 │  ├─ uninstall
 │  ├─ unlink
 │  └─ update
-├─ search
 ├─ store
 │  ├─ auth
 │  └─ execute