@binaryandthread/cli 0.1.8 → 0.2.0

package/README.md

@@ -23,18 +23,24 @@ A bare `bt` may collide with another binary on your `PATH`. If it does, this pac
 **`btn`** as an alias, `btn browse` works identically. (`npx @binaryandthread/cli …` is always the
 unambiguous form.)
 
+> **The only package is the scoped `@binaryandthread/cli`** (signed, 2FA-published). `npx bnt`,
+> `npx bt`, `npx btn`, and `npx binaryandthread` are **different, unscoped packages owned by
+> strangers** — never run them. Always install the full scoped name.
+
 ## Commands
 
 | command | what it does |
 | --- | --- |
-| `bt browse` | the catalog (interactive ↑/↓ picker on a TTY; `--json` for scripts) |
+| `bt browse` | the catalog as a numbered table (`bt stage <n>`); `--pick` opts into the ↑/↓ picker; `--json` for scripts |
 | `bt search <q>` | filter the catalog |
-| `bt view <handle>` | one piece, specs + mockup (`--colour black` renders the black row) |
-| `bt stage <handle>` | add to your cart (`--size`, `--colour`) |
+| `bt view <n\|slug>` | one piece, specs + mockup (`--colour black` renders the black row) |
+| `bt stage <n\|slug>` | add to your cart (`--size`, `--colour`) |
+| `bt blame <n\|slug>` | the design's lore + sources (git blame, for motifs) |
 | `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 region` | show your ship-to country + currency; `bt region <cc>` to set it (validated), `bt region --list` for every country we ship to |
 | `bt drops` | terminal-visible drops |
 | `bt forget` | wipe your local session + config (keychain token, cart, email) |
 
@@ -46,9 +52,16 @@ unambiguous form.)
 | `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 |
+| `--region <cc>` | ship-to country for this command (ISO-2), overriding your saved region |
+
+**Region & currency.** We ship internationally, so prices + shipping are shown in your ship-to
+country's currency. Set it once with `bt region <cc>` (or `bt config set region <cc>`), override it
+per-command with `--region <cc>`, and see the full list with `bt region --list`. Setting an
+unshippable country is refused, and the money commands (`stage` / `checkout`) fail closed rather than
+charge you in a substituted currency.
 
 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`.
+Local config (cart id, email, region, defaults) lives at `~/.config/bt/config.json`.
 
 ## Scripting: `--json` output & exit codes
 
@@ -59,8 +72,9 @@ skips the interactive confirm so it never hangs in CI. Field shapes (stable, saf
 | --- | --- |
 | `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 cart` | `{ cart_id, items: [{ id, title, colour, qty, total }], total, total_excludes_shipping }` |
+| `bt checkout` | `{ status: "placed"\|"timeout"\|"expired", order_id?, display_id?, total?, currency?, checkout_url? }` |
+| `bt region` | `{ region, currency, matched, home }` · `--list` → `{ regions: [{ currency, countries[] }] }` |
 | `bt whoami` | `{ authenticated, tier, commits, standing_pct, token_expires_at, token_expired }` |
 | `bt order <id>` | `{ display_id, status, fulfillment_status?, tracking? }` |