Add doc search command (JSON documentation search)

[nelsonwittwer]

What

Adds shopify doc search --query <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 "<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 --query "subscribe to webhooks"
shopify doc search --query "create a product" --api-name admin --api-version latest

🎩 Testing instructions

doc search hits a public endpoint on shopify.dev (/assistant/search) — no auth, no app, no login required. It just needs network access and prints JSON to stdout.

# 1. Check out this branch and build (dev.js runs the prebuilt bundle, so a build is required)
cd <your cli checkout>
git checkout search-vector-store-json && git pull
pnpm nx build cli

Run commands from the repo root via node packages/cli/bin/dev.js …:

1. Basic query → well-formed JSON

node packages/cli/bin/dev.js doc search --query "subscribe to webhooks" | jq 'length'
#   → a number (count of chunks), with no jq parse error

2. API/version filters are forwarded

node packages/cli/bin/dev.js doc search --query "create a product" --api-name admin --api-version latest | jq '.[0]'
#   → the first result object

3. Invalid version (with an api-name) surfaces the helpful error

node packages/cli/bin/dev.js doc search --query "create a product" --api-name admin --api-version 1999-01
#   → "Search failed: Invalid api_version '1999-01' for api_name 'admin'. Available versions: …"  (exit non-zero)

Note: the endpoint only validates the version in the context of an --api-name. A bad --api-version on its own is silently ignored and still returns results.

4. Required arg + help

node packages/cli/bin/dev.js doc search          # → "Missing required flag query"
node packages/cli/bin/dev.js doc search --help   # → usage, description, examples, --api-name / --api-version flags

Inspecting the Monorail analytics payload

This branch is rebased on the app-context telemetry PR (#7771), so every command emits a command-analytics event. To see exactly what would be sent to Monorail — without sending it — set two env vars:

• SHOPIFY_CLI_NO_ANALYTICS=1 — dump the payload via debug logging instead of POSTing it.
• SHOPIFY_FLAG_VERBOSE=1 — raise the log level so the debug line prints.

SHOPIFY_CLI_NO_ANALYTICS=1 SHOPIFY_FLAG_VERBOSE=1 \
  node packages/cli/bin/dev.js doc search --query "webhooks" 2>&1 \
  | grep "Skipping command analytics"
#   → a "Skipping command analytics, payload: {…}" line with "command": "doc search"

To confirm the inherited app-context hook, run the same command from inside an app directory while logged in — the payload then also carries app-level identifiers (api_key, project_type, app_*). Run it from a non-app directory and those fields are absent.

I saw the APP metrics broadcast via monorail when executing in the path of an app.

When not in the path of an app (in this case in the path of the CLI that I pulled down) - I did not broadcast app context.

Related

• Add shopify doc fetch command to download MD doc 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.

[durga256]

nit: doc search since query is required

[durga256]

use shopifyFetch?

[durga256]

also need to handle network errors gracefully

[kaylarobinson077]

Looking through the existing cli monorail schema, nothing stands out to me as a pre-existing fit for capturing doc search results. My suggestion would be that we add a new monorail field cmd_doc_search_result where we put the json result, then when we extend to validate and other commands, add in related fields like cmd_validate_passes.

Additionally, currently the args monorail field is flagged as PII, so anything we are passing in there (e.g. the search query) is redacted after 30 days. The pattern followed here for cases where we want to retain the flags for longer duration is to additionally log them in a separate field, so we might consider also adding a field like cmd_doc_search_query to explicitly log the search query and not flag it as PII to retain. Not directly related to this PR, but this also is impacting any vars we are saving through the agent env vars, as they're subject to the same PII policy.

So, if this sounds reasonable, I can update the monorail schema to include cmd_doc_search_query and cmd_doc_search_result. For doc fetch, maybe I'll also add in cmd_doc_fetch_query (but skip result there, since it's just the docs content for the requested link?)

[nelsonwittwer]

@kaylarobinson077 - I think the cleaner solution for tracking search would be on the search handler. That one hanbdler is where all search traffic goes already

[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/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.
  *

[kaylarobinson077]

@kaylarobinson077 - I think the cleaner solution for tracking search would be on the search handler. That one hanbdler is where all search traffic goes already

​Is the search handler something that lives within this command, or is it something outside of CLI? My home is that we can track the query and result in the regular CLI monorail event, so everything lives together in one place in terms of where the data lands.