# CLI reference

Install the shop command, then search, check out, track orders and sign in from a terminal or an agent's shell.

`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

```sh
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:

```sh
shop --version
```

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

## Commands

| Command | Tool | Sign-in |
| --- | --- | --- |
| `shop search [query]` | `search_catalog` | Optional |
| `shop catalog lookup <ids...>` | `lookup_catalog` | Optional |
| `shop catalog get <id>` | `get_product` | Optional |
| `shop cart create`, `shop cart get <id>`, `shop cart update <id>` | `create_cart`, `get_cart`, `update_cart` | Optional |
| `shop checkout create`, `shop checkout get <id>`, `shop checkout update <id>` | `create_checkout`, `get_checkout`, `update_checkout` | Optional |
| `shop checkout complete <id>` | `complete_checkout` | Optional |
| `shop order search [query]` | `search_orders` | Required |
| `shop account` | `get_account` | Required |
| `shop approval create`, `shop approval get <id>`, `shop approval update`, `shop approval cancel <id>`, `shop approval complete` | The five [approval tools](approvals.md) | Required |
| `shop call <tool> --arguments <json>` | Any tool, by name | Depends on the tool |

These commands work without a tool call:

| Command | What it does |
| --- | --- |
| `shop account login`, `shop account logout` | Sign in on this device, or remove the sign-in. See [Sign in and credentials](#sign-in-and-credentials). |
| `shop tools` | Lists every tool command, without contacting the server |
| `shop skill` | Prints the CLI's skill for agents |
| `shop <command> --help` | Shows a command's flags. `shop --help --all` shows every command with its flags. |

### Flags and full arguments

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

```sh
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.

```sh
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:

```sh
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:

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

On failure, `error` says what went wrong:

```json
{
  "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>"
  }
}
```

| Field | What it holds |
| --- | --- |
| `code` | The kind of failure, from the table below |
| `message` | What happened, in plain words |
| `retryable` | `true` only when no response came back and repeating the command can't cause a second effect |
| `next` | One to three steps the CLI suggests, when it has any |
| `details` | More about the failure. For a tool error, `details.structuredContent` holds the tool's document. |
| `request_id` | The server's ID for the request, when the server answered |

The exit code follows `code`:

| Exit code | `code` | Meaning |
| --- | --- | --- |
| 0 | | Success |
| 1 | `transport` | No response came back. `details.sent` says whether the request was sent in full. |
| 2 | `usage`, `invalid_input` | The command or its arguments are wrong, and nothing was sent |
| 3 | `auth_required` | The command needs sign-in |
| 4 | `upstream` | The tool returned an error |
| 4 | `precondition_failed` | A `--patch` test failed, or the checkout can't be edited any more. The update wasn't sent. |
| 4 | `protocol_mismatch` | The server's answer wasn't one the CLI accepts |

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:

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

[Edit a cart or checkout](checkout.md#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](checkout.md#complete-a-checkout) shows.

## Sign in and credentials

```sh
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](sign-in.md#with-the-cli) 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:

| System | Path |
| --- | --- |
| macOS and Linux | `$XDG_CONFIG_HOME/shop-node-wasm/credentials.json`, or `~/.config/shop-node-wasm/credentials.json` |
| Windows | `%LOCALAPPDATA%\shop-node-wasm\credentials.json` |

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

| Variable | What it does |
| --- | --- |
| `SHOP_AUTH_FILE` | The absolute path of the credential file |
| `SHOP_MCP_URL` | Another compatible server to send commands to |
| `SHOP_SKIP_SKILL_INSTALL` | Skips installing the skill during `npm install` |

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

```sh
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](connect.md#claude-code) explains why it shouldn't have both.