@usethrottle/cli 1.0.4 → 2.0.0

package/README.md

@@ -5,7 +5,9 @@
 
 # @usethrottle/cli
 
-Command-line tool for the Throttle multi-tenant payments platform.
+Command-line tool for the Throttle multi-tenant payments platform — manage
+orders, payments, customers, subscriptions, discounts, webhooks, events, and
+embed config from your terminal.
 
 ## Install
 
@@ -13,56 +15,200 @@ Command-line tool for the Throttle multi-tenant payments platform.
 npm install -g @usethrottle/cli
 ```
 
-## Usage
+This installs a `throttle` binary (Node >= 20).
 
-### Connect a BigCommerce store
+## Auth & profiles
+
+The CLI authenticates every request with a Throttle secret key (`sk_test_…` /
+`sk_live_…`). You can supply that key on every invocation, via an environment
+variable, or once via a saved local profile.
+
+Create a profile:
 
 ```bash
-throttle bc-connect
+throttle config set prod --api-key sk_live_xxxxxxxxxxxx --label "Production"
 ```
 
-You'll be prompted for:
+`--api <url>` may be added to point a profile at a non-default API base URL
+(defaults to `https://api.usethrottle.dev`). Manage profiles with:
 
-1. Your Throttle API key (sk\_\*) — create one in the Throttle dashboard.
-2. Your BigCommerce store hash (the part of your store URL after `stores/`)
-3. Your BigCommerce API token (Settings → API accounts → Create V2/V3 API token; needs Modify scopes for Orders, Customers, Carts, Webhooks)
+```bash
+throttle config use <profile>       # set the default profile
+throttle config list                # list profiles (keys masked)
+throttle config remove <profile>    # delete a profile
+```
 
-Or non-interactive:
+The first profile you create becomes the default automatically.
+
+### Auth precedence
+
+For both the API key and the API base URL, the CLI resolves the effective
+value in this order:
+
+1. `--api-key` / `--api` flag passed on the command line
+2. `$THROTTLE_API_KEY` / `$THROTTLE_API_URL` environment variable
+3. The selected profile (`--profile <name>`, or the default profile if
+   `--profile` is omitted)
+
+If no key is found through any of these, the command fails with an error
+telling you how to set one.
+
+### Where config is stored
+
+Profiles live in `~/.throttle/config.json` (override the directory with
+`$THROTTLE_CONFIG_HOME`). The file is written with `chmod 0600`.
+
+**Keys are stored in plaintext** inside that file — the same posture as the
+Stripe CLI and GitHub CLI credential stores. Anyone with read access to your
+`$HOME` can read the raw key; treat the machine you run this on accordingly.
+
+## Global flags
+
+These apply to any subcommand:
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Machine-readable JSON output (implies non-interactive; skips confirmation prompts) |
+| `-q, --quiet` | Suppress the startup banner |
+| `--profile <name>` | Config profile to use |
+| `--api-key <sk_>` | API key (overrides profile / `$THROTTLE_API_KEY`) |
+| `--api <url>` | API base URL (overrides profile / `$THROTTLE_API_URL`) |
+| `-y, --yes` | Skip confirmation prompts |
+| `-v, --version` | Print the CLI version |
+
+## Command reference
+
+Money-moving and other state-changing commands (cancel, refund, capture,
+delete, rotate-secret, replay, etc.) prompt for confirmation before acting.
+Pass `-y`/`--yes` to skip the prompt for scripting or CI. Add `--json` to any
+read command to get machine-readable output instead of a table.
+
+### `config` — local profiles
 
-```bash
-throttle bc-connect --api-key sk_xxx --store-hash abc123 --access-token tok_xxx
+```
+throttle config set <profile> --api-key sk_... [--api <url>] [--label <text>]
+throttle config use <profile>
+throttle config list [--json]
+throttle config remove <profile>
 ```
 
-### Disconnect a store
+### `whoami` — active key context
 
-```bash
-throttle bc-disconnect conn_xxx
+```
+throttle whoami
 ```
 
-(Soft-delete; throttle hard-deletes after 90 days.)
+Shows the environment and granted scopes for the resolved API key.
 
-### Embed config (allowlist + branding)
+### `orders` (+ `fulfillments`)
 
-The `<PaymentEmbed/>` / `<CheckoutEmbed/>` React components and the
-hosted page in iframe mode require your parent origin to be on the
-merchant's allowlist before they'll render.
+```
+throttle orders list --status completed
+throttle orders get <id>
+throttle orders cancel <id>
+throttle orders export [--status <s>] [--payment-status <s>] [--type <t>] [--source <s>] [-o, --out <file>]
+throttle orders line-items <id> [--add <json>] [--update <json>] [--remove <ids>]
+
+throttle orders fulfillments list <orderId>
+throttle orders fulfillments get <orderId> <id>
+throttle orders fulfillments create <orderId> [--items <json>]
+throttle orders fulfillments processing|complete|cancel <orderId> <id>
+throttle orders fulfillments ship <orderId> <id> --carrier <c> --tracking <t>
+```
 
-```bash
-throttle embed-config show
+`orders list` also accepts `--payment-status`, `--type`, `--source`,
+`-q/--query`, `--limit`, `--cursor`. `orders export` writes CSV to stdout, or
+to `--out <file>` when given.
+
+### `returns` — RMA / exchanges
+
+```
+throttle returns list --order <orderId>
+throttle returns open --order <orderId> --items <json> [--reason <r>] [--restock]
+throttle returns get <id>
+throttle returns transition <id> --action approve|receive|complete|reject|cancel
+throttle returns exchange <id> --items <json>
+```
+
+### `payments`
+
+```
+throttle payments refund pay_1 --amount 500 --reason "partial"
+throttle payments get <id>
+throttle payments capture <id> [--amount <cents>]
+throttle payments resend-invoice <id>
+```
+
+`--amount` is in minor units; omit it on `refund`/`capture` to act on the full
+balance / full authorized amount.
+
+### `customers` (+ `addresses`)
 
-throttle embed-config set \
-  --origins https://shop.example.com,https://staging.shop.example.com \
-  --primary "#ff6b00" \
-  --logo https://shop.example.com/logo.png \
-  --merchant-name "Shop"
 ```
+throttle customers list [-q, --query <text>] [--limit <n>] [--cursor <c>]
+throttle customers get <id>
+throttle customers create --email <e> [--name <n>] [--external-id <x>]
+throttle customers update <id> [--email <e>] [--name <n>] [--external-id <x>]
+
+throttle customers addresses list <id>
+throttle customers addresses add <id> --json-body <json>
+throttle customers addresses update <id> <addrId> --json-body <json>
+throttle customers addresses remove <id> <addrId>
+```
+
+### `subscriptions`
 
-Origins must be `https://host[:port]`. No paths, no trailing slashes, no
-wildcards. Up to 20 entries.
+```
+throttle subscriptions list [--customer <id>] [--limit <n>] [--cursor <c>]
+throttle subscriptions get <id>
+throttle subscriptions cancel <id> [--at-period-end]
+throttle subscriptions pause <id>
+throttle subscriptions resume <id>
+throttle subscriptions change-plan <id> --amount <cents> --interval <i> [--plan-reference <r>] [--plan-name <n>] [--effective now|period_end]
+throttle subscriptions cancel-pending-change <id>
+```
 
-## Configuration
+### `discounts`
+
+```
+throttle discounts list
+throttle discounts create --json-body <json>
+throttle discounts toggle <id> --active|--inactive
+throttle discounts delete <id>
+```
+
+### `webhooks` (`endpoints` + `deliveries`)
+
+```
+throttle webhooks endpoints create --url https://x/hook --events order.created
+throttle webhooks endpoints list
+throttle webhooks endpoints update <id> [--url <u>] [--events <list>] [--active <bool>]
+throttle webhooks endpoints delete <id>
+throttle webhooks endpoints send-test <id>
+throttle webhooks endpoints rotate-secret <id>
+
+throttle webhooks deliveries list [--endpoint <id>] [--status <s>]
+throttle webhooks deliveries get <id>
+throttle webhooks deliveries replay <id>
+```
+
+`--events` is a comma-separated list of event types.
+
+### `events` — emitted events + catalog
+
+```
+throttle events list [--type <t>] [--limit <n>] [--cursor <c>]
+throttle events get <id>
+throttle events types
+```
+
+### `embed` — allowlist + branding
+
+```
+throttle embed set --origins https://shop.example.com
+throttle embed show
+```
 
-| Flag        | Env var            | Default                       |
-| ----------- | ------------------ | ----------------------------- |
-| `--api`     | `THROTTLE_API_URL` | `https://api.usethrottle.dev` |
-| `--api-key` | `THROTTLE_API_KEY` | (interactive prompt)          |
+`embed set` also accepts `--primary <hex>`, `--logo <url>`, and
+`--merchant-name <name>`; pass at least one flag. Origins are a comma-separated
+list of `https://host[:port]` (no paths, no wildcards, up to 20 entries).