Add doc search command (JSON documentation search)

[nelsonwittwer]

What

Adds shopify doc search <query>, which queries the shopify.dev vector store and prints the most relevant documentation chunks as JSON to stdout.

This is the "discovery" half of the new doc namespace; the "full document" half is doc fetch (#7766). It no longer repurposes the top-level search command — that stays as the human, browser-based command (and is deprecated separately in #7778).

Why

Gives agents (and scripts) a way to discover relevant documentation across shopify.dev as structured JSON, without a browser. Paired with doc fetch, an agent can find the right docs and pull them in full, entirely through the CLI.

Details

• shopify doc search "<query>" — required query; prints the raw JSON response.
• --api-name (e.g. admin, storefront, hydrogen, functions; unknown values ignored).
• --api-version (e.g. 2025-10, latest, current).
• Non-ok responses surface the server's {error} message (e.g. an invalid version lists the valid ones).

shopify doc search "subscribe to webhooks"
shopify doc search "create a product" --api-name admin --api-version latest

Notes

• @shopify/cli: minor.
• Lives under the doc topic (commands/doc/search.ts, registered as doc:search); adds a doc topic description.
• The top-level search command is restored to its original browser behavior in this PR (the deprecation/URL fix lives in Deprecate and fix search #7778).
• Generated artifacts regenerated (oclif manifest, README, dev-docs interface, e2e command-tree snapshot).
• Branches off telemetry-app-context-everywhere (Capture app context (api_key/project_type) in analytics for every command #7771), so it inherits the app-context telemetry hook automatically.

Related

• Add doc fetch command (download docs from shopify.dev) #7766 — doc fetch (full-document retrieval).
• Deprecate and fix search #7778 — deprecates the old browser search, pointing users to doc search.

🤖 Generated with Claude Code

[dmerand]

❤️

[dmerand]

Should discuss this contract with @nickwesselman . I'd assume that shopify search could just have a --fetch-doc param rather than a whole separate command for that case.

[nickwesselman]

Having second thoughts about using shopify search for this.

I'm sure use of shopify search is near-zero, but should we stick to our SemVer committment, and create a new command? We could fix the existing command or just deprecate it.

This would also give us an opportunity to apply our CLI design guidelines to a new command. e.g. The shopify search use of positional arguments is against those guidelines.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/common/url.d.ts

@@ -12,20 +12,4 @@ export declare function isValidURL(url: string): boolean;
  * @param url - The string to parse into a URL.
  * @returns A URL object if the parsing is successful, undefined otherwise.
  */
-export declare function safeParseURL(url: string): URL | undefined;
-/**
- * Extracts the lowercased hostname from a URL-shaped string. Tolerates
- * bare hosts (without a scheme) and inputs that come back from APIs as
- * either  or .
- *
- * @param value - A URL or bare host string, possibly null/undefined.
- * @returns The lowercased hostname, or undefined when the input is empty.
- */
-export declare function extractHost(value: string | null | undefined): string | undefined;
-/**
- * Extracts the subdomain handle from a  URL or host.
- *
- * @param value - A URL or host string, possibly null/undefined.
- * @returns The myshopify subdomain handle, or undefined when the input isn't a  URL.
- */
-export declare function extractMyshopifyHandle(value: string | null | undefined): string | undefined;
\ No newline at end of file
+export declare function safeParseURL(url: string): URL | undefined;
\ No newline at end of file

packages/cli-kit/dist/public/node/metadata.d.ts

@@ -38,7 +38,6 @@ type CmdFieldsFromMonorail = PickByPrefix<MonorailEventPublic, 'cmd_all_'> & Pic
 declare const coreData: RuntimeMetadataManager<CmdFieldsFromMonorail, {
     commandStartOptions: {
         startTime: number;
-        endTime?: number;
         startCommand: string;
         startTopic?: string;
         startArgs: string[];
@@ -59,7 +58,6 @@ declare const coreData: RuntimeMetadataManager<CmdFieldsFromMonorail, {
 export declare const getAllPublicMetadata: () => Partial<CmdFieldsFromMonorail>, getAllSensitiveMetadata: () => Partial<{
     commandStartOptions: {
         startTime: number;
-        endTime?: number;
         startCommand: string;
         startTopic?: string;
         startArgs: string[];
@@ -79,7 +77,6 @@ export declare const getAllPublicMetadata: () => Partial<CmdFieldsFromMonorail>,
 }, "store_", never>>, addPublicMetadata: (getData: ProvideMetadata<CmdFieldsFromMonorail>, onError?: MetadataErrorHandling) => Promise<void>, addSensitiveMetadata: (getData: ProvideMetadata<{
     commandStartOptions: {
         startTime: number;
-        endTime?: number;
         startCommand: string;
         startTopic?: string;
         startArgs: string[];

packages/cli-kit/dist/public/node/session.d.ts

@@ -47,6 +47,22 @@ export declare function isUserAccount(account: AccountInfo): account is UserAcco
  * @returns True if the account is a ServiceAccount.
  */
 export declare function isServiceAccount(account: AccountInfo): account is ServiceAccountInfo;
+/**
+ * Reports whether the CLI already has stored credentials, without prompting the
+ * user, opening a browser, or making any network request.
+ *
+ * This is a passive, side-effect-free check: it reads the local session store and
+ * returns  when at least one valid session is present. Unlike the
+ *  functions, it never triggers a login flow and never logs
+ * the user out. Because it does not contact the network, it cannot tell whether the
+ * stored token is currently valid/unexpired — only that credentials exist locally.
+ *
+ * Intended for best-effort, opportunistic behaviour (for example, enriching
+ * telemetry only for users who are already logged in).
+ *
+ * @returns True if local credentials exist, false otherwise.
+ */
+export declare function sessionExists(): Promise<boolean>;
 /**
  * Ensure that we have a valid session with no particular scopes.
  *