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
shop skill --install

The package needs Node.js 22.21.0 or later within the 22 line, or any version from 24.5.0 onward (>=22.21.0 <23 || >=24.5.0, with no upper bound on the latter range). npm installation doesn’t install the agent skill automatically: shop skill --install explicitly installs the bundled skill and runtime. Run it again after upgrading the package.

Check the install:

shop --version

shop 1.2.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 --currency USD --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 spend-request 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 stores the sign-in credential here:

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. Treat this file like a password.

shop spend-request get <id> reads status and terms only. --include card explicitly requests issuance or replay; --wait alone doesn’t. A private --output-file <path> export requires that explicit card selection and removes the card from stdout. See Get the card for the file’s contents and handling.

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 --install
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.

shop skill --install copies both the skill and its bundled runtime into the common agent skill directories. Use --dir <path> to choose one directory instead. Re-run installation after every package upgrade so those copies match the installed CLI; shop doctor --dry-run can check them 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.