CLI reference

shop is a command-line client for Shop MCP. Each command calls a tool and prints the result as JSON, so a script or an agent can read it as easily as a person.

Install

npm install --global @shopify/shop@latest

The package needs Node.js 22.21 or later in the 22 line, or 24.5 or later in the 24 line. Installing it also hands the CLI’s skill to npx skills add, so agents on the machine can find it. That step is skipped in CI, or when SHOP_SKIP_SKILL_INSTALL is set, and a failure there doesn’t fail the install.

Check the install:

shop --version

shop 0.1.0 (ucp 2026-08-25, mcp 2026-07-28)

Commands

These commands work without a tool call:

Flags and full arguments

Each command has flags that build the tool’s arguments for you:

shop search 'trail running shoes' --ships-to US --price-max 15000 --size 10 --limit 20
shop catalog get gid://shopify/p/21LZl7P8DjyKRD7lJqv40C --select Size=M --country CA --currency CAD

A few defaults to know:

• --country is US when you leave it out, but the CLI never picks a currency. Pass --currency whenever you filter on price.
• Prices such as --price-max 15000 are in minor units.
• --include-unavailable adds items that can’t be bought right now, which search leaves out by default.
• --variant takes a full variant ID or just the number at its end.
• A value that starts with - has to go in the flag form of its argument, such as --query.

For anything the flags don’t cover, pass the tool’s complete argument object with --arguments, as inline JSON, @file for a file, or - for standard input. --schema prints the schema that object has to match. A command takes flags or --arguments, never both.

shop search --schema
shop search --arguments @search.json
shop call search_catalog --arguments @search.json

Look before you send

--dry-run prints the exact requests a command would make, and --as curl prints the request as a curl command. Neither one sends anything:

shop search 'rain jacket' --country CA --currency CAD --price-max 8000 --as curl

For cart update and checkout update with --patch, the dry run shows both calls: the read, then the update. --as curl works only for a command that makes a single request it knows in full, so it refuses those two, and approval get with a --wait above 0.

Output

Every command prints one JSON envelope. On success, data holds the tool’s result, the same document as structuredContent over MCP:

{ "ok": true, "v": 1, "data": { "ucp": { "version": "2026-08-25" }, "products": [] } }

On failure, error says what went wrong:

{
  "ok": false,
  "v": 1,
  "error": {
    "code": "auth_required",
    "message": "Not signed in on this device",
    "retryable": false,
    "next": [
      "Run shop account login --wait 0 and show the shopper the verification URL and code",
      "Run shop account login --wait 90 to finish once they approve",
      "Retry this command after signing in"
    ],
    "details": { "status": 401 },
    "request_id": "<request id>"
  }
}

The exit code follows code:

Shop MCP’s own suggestions for what to do next stay in the document, at data.next, or at error.details.structuredContent.next for a tool error. error.next is the CLI’s own advice, and a failure can have both.

--format md prints results as Markdown for people to read. Agents should use the default JSON. --verbose writes request and response diagnostics to standard error, with credentials removed.

Edit carts and checkouts

shop cart update and shop checkout update take a JSON Patch with --patch. The CLI reads the current document, applies the patch to it, and sends the whole document back as the update. Each change to a line needs a test of that line’s id before it:

shop checkout update '<checkout id>' --shop tog24.myshopify.com --patch @patch.json

Edit a cart or checkout has examples. shop checkout complete takes the payment instrument with --instrument, preferably from a file or standard input, as Complete a checkout shows.

Sign in and credentials

shop account login --wait 0 --device-name "Sam's laptop"
shop account login --wait 90

The first command starts a sign-in and prints the link and code to show the shopper. The second waits up to 90 seconds for them to approve. Connect a Shop account walks through it. shop account logout removes the sign-in from this device.

Both take --dry-run, which shows the plan without sending or writing anything.

The npm package keeps the credential in a plain-text file:

On macOS and Linux, the CLI creates the file so that only your user can read it, and refuses to use one that other users can read. Set SHOP_AUTH_FILE to an absolute path to keep it somewhere else. The file isn’t encrypted, so treat it like a password.

The CLI sends the credential only to Shop MCP. --url and SHOP_MCP_URL point commands at another compatible server, and commands sent there run without it.

Environment variables

The npm package also reads the usual proxy settings, HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY, SSL_CERT_FILE replaces the certificate authorities it trusts, and NODE_EXTRA_CA_CERTS adds to them.

The skill

shop skill
shop skill references/transactions.md

shop skill prints the CLI’s skill, written for these commands, and shop skill references/<name>.md prints one of its three references: catalog.md, transactions.md or cli.md. Both read from the installed CLI, offline.

An agent that shops through the CLI should load this skill instead of the one Shop MCP serves. Connect an agent explains why it shouldn’t have both.