@usethrottle/cli

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

npm install -g @usethrottle/cli

This installs a throttle binary (Node >= 20).

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:

throttle config set prod --api-key sk_live_xxxxxxxxxxxx --label "Production"

--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:

throttle config use <profile>       # set the default profile
throttle config list                # list profiles (keys masked)
throttle config remove <profile>    # delete a profile

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

throttle config set <profile> --api-key sk_... [--api <url>] [--label <text>]
throttle config use <profile>
throttle config list [--json]
throttle config remove <profile>

whoami — active key context

throttle whoami

Shows the environment and granted scopes for the resolved API key.

orders (+ fulfillments)

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>

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 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

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>

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

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).