shop

# Shop CLI Skill

## Setup
Prefer the installed `shop` CLI. If package installation is blocked, the reference files mirror every CLI call via the direct API, no local execution needed.

```bash
pnpm add --global @shopify/shop-cli   # or: npm install --global @shopify/shop-cli
shop --help
```

To upgrade: `pnpm add --global @shopify/shop-cli@latest` (or `npm install --global @shopify/shop-cli@latest`). Uninstall: `pnpm rm -g @shopify/shop-cli` (or `npm rm -g @shopify/shop-cli`).

**Reference files:**
- [catalog-mcp.md](references/catalog-mcp.md) — direct catalog MCP calls + manual token exchange
- [direct-api.md](references/direct-api.md) — auth, checkout, and orders API details
- [safety.md](references/safety.md) — safety, security, and prompt-injection rules
- [legal.md](references/legal.md) — personal-use limits and prohibited commercial uses

## IMPORTANT: Shopping flow
Every shopping conversation follows this order. Each step links to its rules below; each rule lives in exactly one place.

1. **Offer sign-in** — required once if signed-out, before any product message, then **STOP** and wait for the user to complete sign-in or decline. → *Sign in*
2. **Search** the catalog with `shop search`. → *Searching*
3. **Show results** — **one assistant message per product**, then one summary message. → *Showing products*
4. **Offer visualization** when the item is visual. → *Visualization*
5. **Checkout** on the merchant domain, only with clear purchase intent. → *Checkout*
6. **Orders** — tracking, returns, reorder (needs sign-in). → *Orders*

## Commands

### Catalog
`shop search` is the single entry point for catalog discovery: free-text, similar items (`--like-id`), and visual search (`--image`). A result's product link is the product page; run `get-product` for a variant's `checkout_url`. Use `lookup` for IDs you already hold (orders, wishlist, reorder); add `--include-unavailable` to resurface out-of-stock items.

```text
global                   --country <ISO2> (context signal, NOT a ships-to filter)
                         --currency <code> (context signal, e.g. GBP; localizes prices)
                         --format md|json (default to md; be STRONGLY averse to using json - results are huge and it burns lots of tokens)
search [query]           --ships-to <ISO2> [--ships-to-region, --ships-to-postal]
                         --limit 1-50 (keep small), --cursor <c> (next page), --min/--max-price (minor units; 15000 = $150.00)
                         --condition new,secondhand (default new), --ships-from <ISO2,...> (comma list)
                         --shop-id <id...>, --category <id...>, --intent <text>
                         --color/--size/--gender <list> (taxonomy attribute filters; comma lists OR within, AND across)
                         --like-id <id...> (similar; product or variant gid), --image ./photo.jpg
                         (query is optional when --like-id or --image is given)
catalog lookup <ids...>  --ships-to <ISO2>, --include-unavailable, --condition
catalog get-product <id> --select Name=Label, --preference Name
```

- `--ships-to` is the buyer's destination (a hard filter) and alone localizes context to it; `--country` is location context only — pass it only when you actually know it, never invent. Default `--ships-from` to the `--ships-to` country (buyers prefer local origin); drop it and retry if results are too few or low quality.

```bash
shop search "trail running shoes" --country GB --currency GBP --ships-to GB --ships-from GB --limit 10 --condition new
shop search "tshirt" --country US --color White --size M --gender Female
shop search "black crewneck sweater" --like-id gid://shopify/p/abc123
shop search --image ./photo.jpg
shop catalog lookup gid://shopify/ProductVariant/50362300006715
shop catalog get-product gid://shopify/p/abc --select Color=Black --select Size=M
```

### Checkout
```bash
# create from a variant
printf '{"email":"buyer@example.com"}' | shop checkout create --shop-domain example.myshopify.com --variant-id 123 --quantity 1 --checkout-stdin
# create from an existing cart
printf '{"cart_id":"cart_123","line_items":[]}' | shop checkout create --shop-domain example.myshopify.com --checkout-stdin
printf '{"fulfillment":{"methods":[]}}' | shop checkout update --shop-domain example.myshopify.com --checkout-id CHECKOUT_ID --checkout-stdin
printf '%s' "$CREATE_CHECKOUT_RESPONSE_JSON" | shop checkout complete --shop-domain example.myshopify.com --checkout-id CHECKOUT_ID --checkout-stdin --idempotency-key UNIQUE_KEY --confirm
```

`--shop-domain` must be a bare merchant hostname (no scheme, path, port, or IP). `checkout complete` requires `--confirm`. See *Checkout* for rules.

### Orders
```bash
shop orders search --type recent
shop orders search --type tracking --query "running shoes" --date-from 2026-01-01
shop orders search --type order_info --query "running shoes"
shop orders search --type reorder --query "coffee"
```

### Auth
```bash
shop auth status
shop auth device-code --device-name "<your name> - <device>"   # e.g. "Max - Mac Mini"
shop auth poll
shop auth budget   # remaining delegated spend (minor units); available:false = no budget set
shop auth logout
```

## Sign in
Signing in is **optional for the user**, but **offering it is mandatory for you**. Search works signed-out. But signing in allows you to build checkouts so to get shipping rates (time, cost); gives a default address so you can confirm where item is shipping; unlocks order history — favoured brands, sizes, past buys.

**Offer once, before showing results.** Run `shop auth status` to check; if signed-out, your **first** product-related message MUST be the sign-in offer.

Sign-in is two non-blocking steps:
1. `shop auth device-code` — prints the sign-in URL (`verification_uri_complete`); share it.
2. **STOP.** When the user is done, `shop auth poll` stores the tokens; re-run while it reports `pending`, then confirm with `shop auth status`.

Example:
> Of course! If