Commas CLI

Run your Commas (formerly FanBasis) business from the terminal. The CLI is a thin client for the Commas MCP server — every command maps to an MCP tool, so the CLI automatically stays in sync with the server's capabilities.

npm install
npm run build
npm link        # makes `commas` available globally

Getting started

commas login                 # prompts for your API key (stored in ~/.commas/config.json, mode 0600)
commas status                # server health + current config
commas tools                 # list every tool the server exposes

Commands

# Products
commas products list

# Customers
commas customers search "[email protected]"
commas customers payment-methods <customerId>
commas customers charge <customerId> --payment-method <id> --amount 25.00 --description "Manual rebill"

# Transactions
commas tx list --per-page 50
commas tx get <transactionId>
commas tx session <checkoutSessionId>
commas tx refund <transactionId> --amount 10.00 --reason "Requested by customer"

# Subscriptions
commas subs list
commas subs product <productId>
commas subs cancel <subscriptionId> --session <checkoutSessionId>
commas subs extend --session <id> --user <userId> --days 30

# Checkout sessions (payment links)
commas checkout create --title "Coaching Call" --type onetime_reusable --amount 199
commas checkout get <checkoutSessionId>
commas checkout delete <checkoutSessionId>
commas checkout embedded

# Discount codes
commas discounts list
commas discounts create --code SUMMER20 --type percentage --value 20
commas discounts delete <discountCodeId>

# Webhooks
commas webhooks list
commas webhooks create --url https://example.com/hook --events payment.succeeded,refund.created
commas webhooks test <id> --event payment.succeeded

# Docs
commas docs how do subscription webhooks work

# Escape hatch — call any MCP tool directly
commas call list_products -p per_page=5
commas call create_discount_code --params '{"code":"VIP","type":"fixed","value":500}'

Environments

The server tracks production vs sandbox per MCP session, so the CLI persists your choice locally and re-applies it on every run:

commas env               # show current default
commas env sandbox       # all future commands run against QA/sandbox
commas env production
commas tx list --env sandbox   # one-off override

If the sandbox switch fails, the command aborts rather than silently running against production.

Safety

Money-moving and destructive commands (charge, refund, cancel, delete) use the server's confirmation-token flow: the CLI shows a summary and asks Proceed? (y/N). Pass --yes to auto-confirm (required in non-interactive contexts like scripts and CI).

For scripts and AI agents

Every command accepts --json for machine-readable output, and --yes for non-interactive confirmation. Exit code is 0 on success, 1 on any failure. Credentials can come from $COMMAS_API_KEY instead of the config file.

commas tx list --json | jq '.data[] | select(.status == "failed")'

Configuration

Resolution order: command flags → environment variables → ~/.commas/config.json → defaults.

| Setting | Flag | Env var | Config key | | --- | --- | --- | --- | | API key | --api-key | COMMAS_API_KEY | apiKey | | Server URL | --server | COMMAS_MCP_URL | serverUrl | | Environment | --env | COMMAS_ENV | environment |

Default server: https://hearty-flow-production.up.railway.app/mcp

Development

npm run dev -- tx list       # run from source via tsx
npm run build                # compile to dist/