@binaryandthread/cli

@binaryandthread/cli, bt

Buy a Binary & Thread heavyweight piece 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):

# recommended: install globally for a persistent `bt` on your PATH
npm i -g @binaryandthread/cli
bt browse

# or run without installing (no persistent command):
npx @binaryandthread/cli browse

A bare bt may collide with another binary on your PATH. If it does, this package also installs 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.

The ones you forward

People forward commands, not shops. Each of these installs nothing, buys nothing, and costs the person you send it to about four seconds.

npx @binaryandthread/cli fortune   # a real aphorism from the trade, never an invented one
npx @binaryandthread/cli brew      # ask a clothing company for coffee, get RFC 2324
npx @binaryandthread/cli init      # the welcome, and the three commands that matter
npx @binaryandthread/cli browse    # the whole catalogue, as a numbered table

fortune draws from a fixed pool of genuine, attributable lines. Nothing in it was made up, which is the only reason it is worth passing on.

brew is the house joke, and it is the one design two separate strangers have laughed at. Ask for coffee and the shop answers 418 i'm a teapot, which is a real HTTP status code from a real April Fools' RFC that somehow never died. The article is at /guide/the-joke-that-would-not-die; the garment exists too.

There are a dozen or so other responses hidden in here for commands a developer types by reflex. Listing them would defeat the point.

Commands

command	what it does
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 <n|slug>	one piece, specs + mockup (--colour black renders the black row; --fit oversize shows the other fit of a two-fit design)
bt stage <n|slug>	add to your cart (--size, --colour, --fit regular|oversize; a design sold in both fits needs --fit, or bt config set defaultFit …)
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)

Ten more that the CLI has always had and this table has never listed:

command	what it does
bt init	the first-run welcome and the three-command happy path. What the bare bt points a newcomer at
bt buy <n|slug>	stage and checkout in one, for when you already know what you want
bt status	working-tree state: what is staged, what is in flight
bt config [sub] [key] [value]	local preferences (email, region, default fit). The auth token is never stored here
bt token	prints your keychain JWT for an MCP config. A bearer credential, treat it like one
bt completion <shell>	a shell completion script, to eval in your rc
bt doctor	local diagnostics for a bug report. Sends nothing
bt report [message]	files a bug report: a redacted snapshot, never cards or tokens
bt brew	see above
bt fortune	see above

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
--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, region, 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, price_from, currency, colours[], fits[], channel_stage }] (price is the cheapest fit when price_from)
bt view <handle>	{ id, handle, title, fits[], fit, colours[], unavailable_colours[], specs, variants: [{ id, fit, colour, size, price, currency }] }
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? }

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.