@binaryandthread/cli 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @binaryandthread/cli — `bt`
+
+Buy a Binary & Thread heavyweight tee **from your terminal**, with the ceremony of a production
+deploy. A small, well-tested client over the Store API — the card never touches the terminal.
+
+> `bt` is a dumb client. Every dangerous operation (payment, fulfilment) lives in the backend.
+> Checkout hands you a URL; you pay on the storefront's Stripe page in your own browser.
+
+## Install
+
+Zero-config — it ships pointed at the live store (the publishable key is public by design):
+
+```bash
+# soft-launch tarball (friends): install the .tgz you were handed
+npm i -g ./binaryandthread-cli-0.1.0.tgz
+bt browse
+
+# or, once published:
+npx @binaryandthread/cli browse
+```
+
+A bare `bt` may collide with another binary on your `PATH`; `npx @binaryandthread/cli …` is the
+unambiguous form.
+
+## Commands
+
+| command | what it does |
+| --- | --- |
+| `bt browse` | the catalog (interactive ↑/↓ picker on a TTY; `--json` for scripts) |
+| `bt search <q>` | filter the catalog |
+| `bt view <handle>` | one tee — specs + mockup (`--colour black` renders the black row) |
+| `bt stage <handle>` | add to your cart (`--size`, `--colour`) |
+| `bt cart` / `bt unstage <ref>` | show / remove a line |
+| `bt checkout` | mint a checkout, hand off to the browser to pay, then poll |
+| `bt order <id>` / `bt log` | track an order / your order history (when logged in) |
+| `bt login` / `bt whoami` / `bt logout` | magic-link auth → JWT in your OS keychain |
+| `bt drops` | terminal-visible drops |
+| `bt forget` | wipe your local session + config (keychain token, cart, email) |
+
+## Config (all optional — env overrides the baked-in prod defaults)
+
+| var | notes |
+| --- | --- |
+| `BT_API_URL` | Store API base URL (default: production; set for local dev / staging) |
+| `BT_PUBLISHABLE_KEY` | the **publishable** key — public by design (a secret `sk_` key is rejected) |
+| `NO_COLOR` / `--no-color` | plain output, no ANSI / inline images |
+| `--json` | machine-readable output for scripts / CI |
+
+Your auth token is **never** stored in config — it lives in the OS keychain (`bt login`).
+Local config (cart id, email, defaults) lives at `~/.config/bt/config.json`.
+
+## Scripting: `--json` output & exit codes
+
+Every command takes `--json` for stable, machine-readable output. `bt checkout --json` (or `--yes`)
+skips the interactive confirm so it never hangs in CI. Field shapes (stable — safe to depend on):
+
+| command | `--json` shape |
+| --- | --- |
+| `bt browse` / `bt search` | `[{ id, handle, title, price, currency, colours[], channel_stage }]` |
+| `bt view <handle>` | `{ id, handle, title, price, currency, colours[], sizes[] }` |
+| `bt cart` | `{ cart_id, items: [{ id, title, colour, qty, total }], total, currency }` |
+| `bt checkout` | `{ status: "placed"\|"timeout"\|"expired", order_id?, display_id?, checkout_url? }` |
+| `bt whoami` | `{ authenticated, tier, commits, standing_pct, token_expires_at, token_expired }` |
+| `bt order <id>` | `{ display_id, status, fulfillment_status?, tracking? }` |
+
+**Errors** (`--json`) come back as `{ "error": { "code", "type", "message" } }` and the process
+exits with a distinct code so CI/agents can branch:
+
+| exit | type | meaning |
+| --- | --- | --- |
+| `0` | — | success |
+| `65` | `client_error` / `stale_cart` | bad request / re-stage the cart |
+| `69` | `not_found` | no such product/order |
+| `75` | `rate_limited` / `upstream` | temporary — retry later (a `429` is auto-retried honoring `Retry-After`) |
+| `77` | `auth` | not logged in / forbidden — run `bt login` |
+| `1` | `error` | anything else |
+
+**Rate limits:** the client auto-retries `429` responses, honoring the server's `Retry-After`
+(capped at 10s) before falling back to jittered exponential backoff. A persistent `429` surfaces as
+exit `75` / `type: "rate_limited"`.
+
+The **MCP server** mirrors these as `structuredContent` on every tool result (e.g. `cart_id`,
+`session_id`, `order_id`, `products[]`) so an agent can chain tools without parsing prose.