# shopfast CLI

> A small command-line client for the API that also forwards live events to your local server, signed.

Source: https://shopfa.st/docs/cli

The CLI is one file. It runs on [Bun](https://bun.sh) and needs nothing else.

```sh
curl -fsSLo shopfast.js https://shopfa.st/docs/cli/shopfast.js
bun shopfast.js login --key sk_live_…
```

The key already belongs to your store, so there is no store id to pass: `login` asks `/v1/store` which store the key
reaches and saves the key per profile in `~/.config/shopfast/config.json` (readable only by you).
`--api http://localhost:8787` points it at a development server; `--profile staging` keeps several.
`SHOPFAST_API_KEY` and `SHOPFAST_API_URL` override the saved profile, for CI.

## Commands

| Command | What it does |
| --- | --- |
| `whoami` | The store the profile reaches |
| `products [--limit 20]` | Products as a table |
| `orders [--tab paid] [--limit 20]` | Orders with totals and buyers |
| `events [--type order.paid] [--follow]` | Events from the [event explorer](https://shopfa.st/docs/guides/webhooks#event-explorer); `--follow` keeps polling |
| `listen --forward-to URL [--secret whsec_…]` | Forwards each new event to a local URL, signed |
| `openapi [--out openapi.json]` | Downloads the OpenAPI 3.1 document |
| `api METHOD /v1/store/… [--data JSON]` | Any request; the explicit form works too (`{store}` in `/v1/stores/{store}/…` is your store id) |
| `mcp [--toolsets catalog,orders]` | ShopFast's MCP server over stdio, for AI tools that only start local servers |

## MCP over stdio

Some AI tools only start local MCP servers. `shopfast mcp` is one: it relays stdio to ShopFast's
[MCP server](https://shopfa.st/docs/ai/mcp) with your profile's key, so the tool gets the same tools, confirmations and limits.

```json
{
  "mcpServers": {
    "shopfast": { "command": "shopfast", "args": ["mcp", "--toolsets", "catalog,orders"] }
  }
}
```

`--toolsets` keeps the tool list short; leave it out for every tool. Logs go to stderr, so stdout stays the protocol's.

## Forward events to localhost

```sh
bun shopfast.js listen --forward-to http://localhost:3000/shopfast
```

It prints a signing secret for the session and posts every new event's exact body with `webhook-id`,
`webhook-timestamp` and `webhook-signature` headers, so the [verifier](https://shopfa.st/docs/guides/webhooks#verify-the-signature) you
ship to production runs unchanged. The key needs `webhooks:read`, and events are recorded only while at least one
endpoint subscribes to their type (add a placeholder endpoint for local work).

## Source

The CLI lives in the ShopFast repository at `tools/shopfast/shopfast.ts`. New commands are one `case` each.