> ## Documentation Index
> Fetch the complete documentation index at: https://commet.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The official command-line tool for Commet. Manage billing, forward webhooks, and automate your workflow from the terminal.

> The official command-line tool for Commet. Manage billing, forward webhooks, and automate your workflow from the terminal.

## Install

**pnpm**

```bash theme={null}
pnpm add -g commet
```

**npm**

```bash theme={null}
npm install -g commet
```

**yarn**

```bash theme={null}
yarn global add commet
```

Requires Node.js 18+.

## Authentication

**`commet login`**

Authenticate via browser. Opens a device-code flow and stores your token at `~/.commet/auth.json`.

```bash theme={null}
commet login
```

In CI, set `COMMET_API_KEY` as an environment variable instead.

The CLI uses two kinds of credentials, depending on the command:

| Command type | Credential resolution |
| - | - |
| Resource commands (`customers`, `plans`, `subscriptions`, `usage`, …) | `COMMET_API_KEY` env var → project API key (auto-generated by `commet link`, stored in `.commet/config.json`) → error |
| Platform commands (`orgs`, `link`, `listen`, `create`) | `COMMET_API_KEY` env var → saved credentials from `commet login` |

Resource commands never fall back to your `commet login` credentials — without an API key from the environment or a linked project, they fail and point you to `commet link`.

```bash theme={null}
commet logout     # Remove stored credentials
```

## Setup

**`commet agents setup`**

Prepare an existing repository for coding agents. The command preserves the rest of `AGENTS.md` and manages only its own delimited block, so it is safe to run again or remove later.

```bash theme={null}
commet agents setup
commet agents setup --check --output agent
```

Use `--check --output agent` in automated workflows to verify that the managed instructions are current without rewriting the file.

**`commet doctor`**

Check the installed SDK, project configuration, agent instructions, and local environment before asking an agent to implement billing. Doctor is read-only: it does not contact Commet, modify files, or print secret values.

```bash theme={null}
commet doctor
commet doctor --output agent
```

The agent output is compact and machine-readable enough to paste into an implementation task. For version-specific SDK guidance, start at `node_modules/@commet/node/docs/README.md`.

**`commet link`**

Link this project to a Commet organization. Re-run to switch organizations.

```bash theme={null}
commet link
```

```bash theme={null}
commet link --org acme       # By slug or ID
commet link --clear          # Unlink project
```

| Flag | Required | Description |
| - | - | - |
| `--org <slug-or-id>` | No | Organization slug or ID. Skips interactive selection |
| `--clear` | No | Unlink project from its organization |

**`commet pull`**

Fetch your billing config and generate `commet.config.ts` with typed features and plans.

```bash theme={null}
commet pull
```

```bash theme={null}
commet pull --dry-run        # Preview changes without writing
commet pull --yes            # Skip confirmation
```

| Flag | Required | Description |
| - | - | - |
| `--dry-run` | No | Show what would change without writing any files |
| `-y, --yes` | No | Skip confirmation prompt |

After `commet pull`, your SDK calls get autocomplete for plan codes and feature codes.

**`commet push`**

Push your local `commet.config.ts` to Commet. Creates or updates features and plans to match your config.

```bash theme={null}
commet push
```

```bash theme={null}
commet push --dry-run        # Preview what would change on remote
commet push --yes            # Push without confirmation
```

| Flag | Required | Description |
| - | - | - |
| `--dry-run` | No | Show what would change without pushing |
| `-y, --yes` | No | Skip confirmation prompt |

> [!WARNING]
>
> Feature type changes (`boolean` to `usage`, etc.) are blocked via push. Change them in the dashboard.

**`commet create`**

Scaffold a new Commet project from a template. Creates plans and features in your sandbox organization, generates an API key, and links the project.

```bash theme={null}
commet create
```

```bash theme={null}
commet create myapp -t metered --org acme -y
commet create --list              # List available templates
```

| Flag | Required | Description |
| - | - | - |
| `-t, --template <name>` | No | Template: `fixed`, `seats`, `metered`, `credits`, `balance-ai`, `balance-fixed` |
| `--org <slug>` | No | Sandbox organization slug or ID |
| `--skills` | No | Install agent skills |
| `--no-skills` | No | Skip agent skills installation |
| `-y, --yes` | No | Accept defaults for optional prompts |
| `--ref <ref>` | No | Git ref to fetch templates from. Default: `main` |

**`commet listen`**

Forward webhook events from Commet to your local server. No ngrok or external tunneling needed.

```bash theme={null}
commet listen 3000
```

The argument accepts a port, host:port, or full URL:

```bash theme={null}
commet listen 3000                              # http://localhost:3000/
commet listen localhost:3000/webhooks            # http://localhost:3000/webhooks
commet listen http://local.commet.co:3010/api    # http://local.commet.co:3010/api
```

Filter by event type:

```bash theme={null}
commet listen 3000 --events invoice.created,subscription.activated
```

| Flag | Required | Description |
| - | - | - |
| `<url>` | Yes | Target URL: port (`3000`), host:port, or full URL |
| `--events <types>` | No | Comma-separated event types to forward |

```
  ✓ Authenticated (org: Acme Inc)
  ✓ Connected to Commet webhook stream
  ⟶ Forwarding to http://localhost:3000/
  ⟶ Signing secret: whsec_...

  Ready! Listening for webhook events...

  14:32:01  customer.created              →  200 OK     (12ms)
  14:32:05  subscription.updated          →  200 OK     (8ms)
```

The session stays open until `Ctrl+C`. Events are signed with the displayed secret.

```bash theme={null}
commet orgs               # List all organizations (name, slug, mode)
```

## Customers

Create and manage customers, retrieve details, and handle batch operations.

**`commet customers create`**

Create a customer.

```bash theme={null}
commet customers create --email user@acme.com --id user_123
```

```bash theme={null}
commet customers create \
  --email billing@corp.com \
  --full-name "Acme Corp" \
  --metadata '{"plan":"enterprise"}'
```

| Flag | Required | Description |
| - | - | - |
| `--email <email>` | Yes | Billing email |
| `--id <id>` | No | Custom customer ID |
| `--external-id <id>` | No | ID from your system |
| `--full-name <name>` | No | Full name |
| `--tax-document <value>` | No | Tax document |
| `--timezone <tz>` | No | Timezone |
| `--metadata <json>` | No | Metadata as JSON object |
| `--address <json>` | No | Address as JSON: `{line1, city, postalCode, country}` |
| `--address-id <id>` | No | Existing customer address ID |

```bash theme={null}
commet customers get --id cus_xxx                   # Get a customer by ID
commet customers update --id cus_xxx --email new@acme.com  # Update a customer
commet customers list                                # List all customers
commet customers list --limit 25 --cursor cur_xxx    # Paginate
commet customers list --external-id user_123         # Find by external ID
commet customers create-batch --customers '[{"email":"a@co.com"},{"email":"b@co.com"}]'
```

## Subscriptions

Create, cancel, and manage subscriptions. Change plans, activate addons, and handle balance operations.

**`commet subscriptions create`**

Create a subscription for a customer.

```bash theme={null}
commet subscriptions create \
  --customer-id user_123 \
  --plan-code pro \
  --billing-interval monthly
```

```bash theme={null}
commet subscriptions create \
  --customer-id user_123 \
  --plan-id pln_xxx \
  --price-id pp_argentina \
  --billing-interval yearly \
  --initial-seats '{"team_member":5}' \
  --skip-trial true
```

| Flag | Required | Description |
| - | - | - |
| `--customer-id <id>` | Yes | Customer ID |
| `--plan-code <code>` | One of `plan-code` / `plan-id` | Plan code |
| `--plan-id <id>` | One of `plan-code` / `plan-id` | Plan ID |
| `--billing-interval <interval>` | No | `weekly`, `monthly`, `quarterly`, `semiannual`, `yearly`, `one_time` |
| `--price-id <id>` | No | Selectable plan price. Omit it to use the interval default and its market pricing |
| `--initial-seats <json>` | No | Initial seats as JSON: `{featureCode: count}` |
| `--skip-trial <bool>` | No | Skip trial period |
| `--custom-trial-days <n>` | No | Override the catalog trial duration |
| `--offer-id <id>` | No | Apply an Offer directly. Cannot be combined with `promo-code` or a custom trial |
| `--promo-code <code>` | No | Apply the Offer referenced by a customer-entered code |
| `--provider <provider>` | No | Initial checkout provider override: `stripe`, `commet`, or `dlocal` |
| `--name <name>` | No | Subscription name |
| `--start-date <date>` | No | Start date (ISO 8601) |
| `--success-url <url>` | No | Redirect URL after successful checkout |

**`commet subscriptions cancel`**

Cancel a subscription. Cancels at period end by default.

```bash theme={null}
commet subscriptions cancel --id sub_xxx
```

```bash theme={null}
commet subscriptions cancel --id sub_xxx --immediate true --reason "Customer requested"
```

| Flag | Required | Description |
| - | - | - |
| `--id <id>` | Yes | Subscription ID |
| `--reason <reason>` | No | Cancellation reason |
| `--immediate <bool>` | No | Cancel immediately instead of at period end |

```bash theme={null}
commet subscriptions get-active --customer-id user_123           # Get active subscription
commet subscriptions uncancel --id sub_xxx                       # Revert pending cancellation
commet subscriptions reactivate --id sub_xxx --offer-id ofr_xxx  # Reactivate a canceled subscription with a direct Offer
commet subscriptions change-plan --id sub_xxx --new-plan-id pln_xxx --new-billing-interval yearly  # Change plan
commet subscriptions list                                            # List all subscriptions
commet subscriptions list --customer-id user_123 --status active     # Filter by customer/status
commet subscriptions preview-change --id sub_xxx --plan-id pln_xxx --billing-interval yearly  # Preview proration
commet subscriptions activate-addon --id sub_xxx --addon-id adn_xxx
commet subscriptions deactivate-addon --id sub_xxx --addon-id adn_xxx
commet subscriptions adjust-balance --id sub_xxx --amount 1000 --type balance --reason "Courtesy credit"
commet subscriptions topup-balance --id sub_xxx --amount 5000
commet subscriptions purchase-credits --id sub_xxx --credit-pack-id cpk_xxx
```

## Plans

Create plans, attach features and prices, and configure regional pricing.

**`commet plans create`**

Create a plan.

```bash theme={null}
commet plans create --name "Pro" --code pro
```

```bash theme={null}
commet plans create \
  --name "Developer" \
  --code developer \
  --consumption-model metered \
  --is-public true \
  --block-on-exhaustion true
```

| Flag | Required | Description |
| - | - | - |
| `--name <name>` | Yes | Plan name |
| `--code <code>` | Yes | Plan code |
| `--description <desc>` | No | Plan description |
| `--consumption-model <model>` | No | `metered`, `credits`, or `balance` |
| `--is-public <bool>` | No | Whether plan is publicly visible |
| `--is-free <bool>` | No | Whether plan is free |
| `--block-on-exhaustion <bool>` | No | Block usage when balance/credits exhausted |
| `--plan-group-id <id>` | No | Plan group ID |
| `--metadata <json>` | No | Metadata as JSON object |

**`commet plans add-feature`**

Add a feature to a plan with pricing and limits.

```bash theme={null}
commet plans add-feature \
  --plan-id pln_xxx \
  --feature-id ftr_xxx \
  --included-amount 1000 \
  --overage-enabled true \
  --overage-unit-price 100
```

```bash theme={null}
commet plans add-feature \
  --plan-id pln_xxx \
  --feature-id ftr_xxx \
  --pricing-mode ai_model \
  --margin 30
```

| Flag | Required | Description |
| - | - | - |
| `--plan-id <id>` | Yes | Plan ID |
| `--feature-id <id>` | Yes | Feature ID |
| `--enabled <bool>` | No | Whether feature is enabled |
| `--included-amount <n>` | No | Included usage amount |
| `--unlimited <bool>` | No | Unlimited usage |
| `--overage-enabled <bool>` | No | Enable overage billing |
| `--overage-unit-price <n>` | No | Overage price per unit (fixed pricing) |
| `--pricing-mode <mode>` | No | `fixed` or `ai_model` |
| `--margin <n>` | No | Margin percentage (ai\_model pricing) |
| `--credits-per-unit <n>` | No | Credits per unit |

**`commet plans add-price`**

Add a price to a plan.

```bash theme={null}
commet plans add-price \
  --plan-id pln_xxx \
  --billing-interval monthly \
  --price 2900
```

```bash theme={null}
commet plans add-price \
  --plan-id pln_xxx \
  --billing-interval yearly \
  --price 29000 \
  --trial-days 14
```

| Flag | Required | Description |
| - | - | - |
| `--plan-id <id>` | Yes | Plan ID |
| `--billing-interval <interval>` | Yes | `weekly`, `monthly`, `quarterly`, `semiannual`, `yearly`, `one_time` |
| `--price <n>` | One of `price` / `inherits-from-price-id` | Base price in the currency's minor unit |
| `--inherits-from-price-id <id>` | One of `price` / `inherits-from-price-id` | Base price inherited by a selectable variant |
| `--trial-days <n>` | No | Trial period in days |
| `--is-default <bool>` | No | Set as default price |
| `--included-balance <n>` | No | Included balance amount |
| `--included-credits <n>` | No | Included credits amount |
| `--market-prices <json>` | Required for a variant | Market prices as `{marketGroupId, currency, price}` objects |
| `--metadata <json>` | No | Price metadata |

Create a selectable variant that changes only Argentina and inherits the rest of the base price:

```bash theme={null}
commet plans add-price \
  --plan-id pln_xxx \
  --billing-interval monthly \
  --inherits-from-price-id pp_base \
  --market-prices '[{"marketGroupId":"pmg_argentina","currency":"ars","price":1500000}]'
```

```bash theme={null}
commet plans list                                    # List all plans
commet plans list --include-private true              # Include private plans
commet plans get --id pro                            # Get plan details
commet plans update --id pln_xxx --name "Pro Plus" --description "For growing teams" --metadata '{}' --is-public true  # Update a plan
commet plans delete --id pln_xxx                    # Delete a plan
commet plans set-visibility --id pln_xxx --is-public false
commet plans update-feature --plan-id pln_xxx --feature-id ftr_xxx --included-amount 2000
commet plans remove-feature --plan-id pln_xxx --feature-id ftr_xxx
commet plans update-price --plan-id pln_xxx --price-id pp_xxx --price 3900
commet plans delete-price --plan-id pln_xxx --price-id pp_xxx
commet plans set-default-price --plan-id pln_xxx --price-id pp_xxx
```

### Regional prices

Set local currency overrides for a price.

```bash theme={null}
commet plans set-regional-prices \
  --plan-id pln_xxx \
  --price-id pp_xxx \
  --overrides '[{"currency":"EUR","price":2700},{"currency":"BRL","price":14900}]'
```

```bash theme={null}
commet plans delete-regional-prices --plan-id pln_xxx --price-id pp_xxx
```

## Features

Manage the organization's feature catalog.

**`commet features create`**

Create a feature.

```bash theme={null}
commet features create --code api_calls --name "API Calls" --type usage --unit-name calls
```

| Flag | Required | Description |
| - | - | - |
| `--code <code>` | Yes | Feature code |
| `--name <name>` | Yes | Feature name |
| `--type <type>` | Yes | `boolean`, `usage`, `seats`, or `quota` |
| `--description <desc>` | No | Feature description |
| `--unit-name <name>` | No | Unit name for metered features |

```bash theme={null}
commet features list                                             # List the feature catalog
commet features get --code api_calls                             # Get a feature definition
commet features update --code api_calls --name "API Requests" --description "HTTP API calls" --unit-name requests  # Update a feature
commet features delete --code api_calls                          # Delete a feature
```

## Feature Access

Check a customer's feature access and usage.

```bash theme={null}
commet feature-access list --customer-id user_123                       # List feature access for a customer
commet feature-access get --customer-id user_123 --code api_calls       # Get feature access details
```

Use `commet usage check --customer-id user_123 --feature-code api_calls --quantity 1` for a prospective consumption decision.

## Seats

Manage seat allocations for per-seat billing.

**`commet seats add`**

Add seats for a customer.

```bash theme={null}
commet seats add --customer-id user_123 --feature-code team_member
```

```bash theme={null}
commet seats add --customer-id user_123 --feature-code team_member --count 5
```

| Flag | Required | Description |
| - | - | - |
| `--customer-id <id>` | Yes | Customer ID |
| `--feature-code <code>` | Yes | Feature code |
| `--count <n>` | No | Number of seats to add. Default: `1` |

```bash theme={null}
commet seats remove --customer-id user_123 --feature-code team_member
commet seats set --customer-id user_123 --feature-code team_member --count 10
commet seats set-all --customer-id user_123 --seats '{"team_member":5,"admin":2}'
commet seats get-balance --customer-id user_123 --feature-code team_member
commet seats get-all-balances --customer-id user_123
```

## Usage

Track consumption events and check remaining allowance.

**`commet usage track`**

Track a usage event. Supports value-based tracking and AI model token tracking.

```bash theme={null}
commet usage track --feature-code api_calls --customer-id user_123 --value 1
```

```bash theme={null}
commet usage track \
  --feature-code gpt-4o \
  --customer-id user_123 \
  --model gpt-4o \
  --input-tokens 500 \
  --output-tokens 150 \
  --cache-read-tokens 200
```

| Flag | Required | Description |
| - | - | - |
| `--feature-code <code>` | Yes | Feature code |
| `--customer-id <id>` | Yes | Customer ID |
| `--value <n>` | One of `value` / `model` | Usage value (standard tracking) |
| `--model <model>` | One of `value` / `model` | AI model name (token tracking) |
| `--input-tokens <n>` | No | Input tokens (model tracking) |
| `--output-tokens <n>` | No | Output tokens (model tracking) |
| `--cache-read-tokens <n>` | No | Cache read tokens (model tracking) |
| `--cache-write-tokens <n>` | No | Cache write tokens (model tracking) |
| `--event-id <id>` | No | Caller-owned event ID for deduplication. Max 200 characters |
| `--timestamp <ts>` | No | Event timestamp (ISO 8601) |
| `--properties <json>` | No | Event properties as a JSON array of `{ "property": string, "value": string }` entries |

```bash theme={null}
commet usage check --customer-id user_123 --feature-code api_calls --quantity 1
```

## Addons

Create and manage purchasable feature extensions.

**`commet addons create`**

Create an addon.

```bash theme={null}
commet addons create \
  --name "Extra Storage" \
  --base-price 500 \
  --feature-id ftr_xxx \
  --consumption-model metered
```

```bash theme={null}
commet addons create \
  --name "Priority Support" \
  --base-price 2900 \
  --feature-id ftr_xxx \
  --consumption-model boolean
```

| Flag | Required | Description |
| - | - | - |
| `--name <name>` | Yes | Addon name |
| `--base-price <n>` | Yes | Base price in cents |
| `--feature-id <id>` | Yes | Feature ID |
| `--consumption-model <model>` | Yes | `boolean`, `metered`, `credits`, or `balance` |
| `--description <desc>` | No | Addon description |
| `--included-units <n>` | No | Included units (metered) |
| `--overage-rate <n>` | No | Overage rate (metered/balance) |
| `--credit-cost <n>` | No | Credit cost (credits) |

```bash theme={null}
commet addons list                                   # List all addons
commet addons list --limit 25 --cursor cur_xxx       # Paginate
commet addons get --id adn_xxx                     # Get addon details
commet addons update --id adn_xxx --name "Extra Storage Pro" --description "100GB extra" --base-price 900 --included-units 100 --overage-rate 10  # Update an addon
commet addons delete --id adn_xxx                  # Delete an addon
commet addons list-active --customer-id user_123     # List active addons for a customer
```

## Credit Packs

Create and manage credit packs for credit-based plans.

```bash theme={null}
commet credit-packs create --name "500 Credits" --credits 500 --price 4900
commet credit-packs list                             # List all credit packs
commet credit-packs update --id cpk_xxx --price 3900  # Update a credit pack
commet credit-packs delete --id cpk_xxx               # Delete a credit pack
```

| Flag | Required | Description |
| - | - | - |
| `--name <name>` | Yes (create) | Credit pack name |
| `--credits <n>` | Yes (create) | Number of credits |
| `--price <n>` | Yes (create) | Price in cents |
| `--description <desc>` | No | Credit pack description |
| `--is-active <bool>` | No | Whether credit pack is active |

## Plan Groups

Organize plans into groups for pricing tables and the customer portal.

```bash theme={null}
commet plan-groups create --name "Main Plans" --description "Primary pricing tiers" --is-public true
commet plan-groups list                              # List all plan groups
commet plan-groups list --limit 25 --cursor cur_xxx  # Paginate
commet plan-groups get --id plg_xxx                   # Get plan group details
commet plan-groups add-plan --id plg_xxx --plan-id pln_xxx --sort-order 1
commet plan-groups remove-plan --id plg_xxx --plan-id pln_xxx
commet plan-groups reorder-plans --id plg_xxx --plan-ids '["pln_a","pln_b","pln_c"]'
commet plan-groups update --id plg_xxx --name "Updated Plans" --description "New description" --is-public false
commet plan-groups delete --id plg_xxx                # Delete a plan group
```

## Invoices

List invoices, download PDFs, and create adjustments.

**`commet invoices create-adjustment`**

Create an adjustment invoice. Use a negative amount for credits.

```bash theme={null}
commet invoices create-adjustment \
  --customer-id cus_xxx \
  --amount -500 \
  --description "Courtesy credit"
```

| Flag | Required | Description |
| - | - | - |
| `--customer-id <id>` | Yes | Customer ID |
| `--amount <n>` | Yes | Amount in cents. Negative for credit |
| `--description <desc>` | No | Adjustment description |
| `--metadata <json>` | No | Metadata as JSON object |

```bash theme={null}
commet invoices list                                     # List all invoices
commet invoices list --limit 25 --cursor cur_xxx         # Paginate
commet invoices list --subscription-id sub_xxx           # Filter by subscription
commet invoices list --customer-id cus_xxx --status paid # Filter by customer/status
commet invoices get --id inv_xxx                          # Get invoice details
commet invoices get-download-url --id inv_xxx             # Get signed PDF URL
commet invoices send --id inv_xxx                         # Send invoice by email
commet invoices update-status --id inv_xxx --status void  # Update status (paid, void)
```

## Payments

Create hosted payment links and charge saved payment methods. One-time payments, no subscription or plan required. See [Accept One-Time Payments](https://commet.co/docs/accept-one-time-payments.md) for the full lifecycle.

**`commet payments create`**

Create a hosted payment link. The customer opens the returned `url` and pays with any card.

```bash theme={null}
commet payments create \
  --amount 25000 \
  --currency usd \
  --description "Annual report"
```

```bash theme={null}
commet payments create \
  --amount 25000 \
  --currency usd \
  --description "Annual report" \
  --customer-id user_123 \
  --success-url https://yourapp.com/thanks
```

| Flag | Required | Description |
| - | - | - |
| `--amount <n>` | Yes | Amount in cents |
| `--currency <currency>` | Yes | Currency code (e.g. `usd`) |
| `--description <desc>` | Yes | Shown on the payment link, invoice, and receipt |
| `--customer-id <id>` | No | Customer ID |
| `--success-url <url>` | No | Redirect URL after successful payment |
| `--metadata <json>` | No | Metadata as JSON object |

```bash theme={null}
commet payments charge --customer-id user_123 --amount 25000 --currency usd --description "Annual report"  # Charge a vaulted payment method off-session
commet payments get --id pay_xxx                          # Get payment details
commet payments list --customer-id user_123 --limit 20    # List payments
commet payments cancel --id pay_xxx                       # Cancel a pending payment link
```

## Transactions

List transactions, process refunds, and retry failed payments.

```bash theme={null}
commet transactions list                                  # List all transactions
commet transactions list --limit 20 --cursor cur_xxx     # Paginate
commet transactions list --status succeeded              # Filter by status
commet transactions list --customer-email user@acme.com  # Filter by customer email
commet transactions get --id txn_xxx                      # Get transaction details
commet transactions refund --id txn_xxx                   # Full refund
commet transactions retry --id txn_xxx                    # Retry failed payment
```

## Offers

Create reusable Offers independently from plans and distribution channels.

```bash theme={null}
commet offers create \
  --name "14 days free, then 25% off" \
  --phases '[{"type":"free_trial","durationDays":14},{"type":"percentage","percentage":2500,"durationCycles":3}]'
```

`percentage` uses basis points, so `2500` means 25%. Other phase types are `free_trial`, `amount_off`, and `fixed_price`.

```bash theme={null}
commet offers list --active true
commet offers get --id ofr_xxx
commet offers update --id ofr_xxx --name "Launch offer" --phases '[{"type":"fixed_price","prices":[{"currency":"usd","amount":900}],"durationCycles":2}]'
commet offers delete --id ofr_xxx
```

An Offer does not contain `purpose` or plan-price associations. Attach a compatible Offer to a base price in the Dashboard for automatic introductory selection, pass its ID directly as `offerId`, or reference a single-discount Offer from a Promo Code.

## Promo Codes

Create and manage customer-entered distribution codes for Offers.

**`commet promo-codes create`**

Create a promo code.

```bash theme={null}
commet promo-codes create \
  --code SUMMER25 \
  --offer-id ofr_summer25 \
  --max-redemptions 100
```

```bash theme={null}
commet promo-codes create \
  --code ANNUAL \
  --offer-id ofr_annual \
  --billing-interval yearly \
  --plan-ids '["pln_pro","pln_team"]' \
  --expires-at 2026-12-31
```

| Flag | Required | Description |
| - | - | - |
| `--code <code>` | Yes | Promo code string |
| `--offer-id <id>` | Yes | Offer ID with exactly one `percentage` or `amount_off` phase |
| `--billing-interval <interval>` | No | Restrict redemption to one billing interval |
| `--max-redemptions <n>` | No | Maximum number of redemptions |
| `--expires-at <date>` | No | Expiration date (ISO 8601) |
| `--plan-ids <json>` | No | Restrict to specific plan IDs (JSON array) |

```bash theme={null}
commet promo-codes list                              # List all promo codes
commet promo-codes list --limit 25 --cursor cur_xxx  # Paginate
commet promo-codes get --id prc_xxx                  # Get promo code details
commet promo-codes update --id prc_xxx --active false --max-redemptions 50 --expires-at 2026-12-31 --plan-ids '["pln_pro"]'  # Update
```

## Markets

Define reusable country groups, then reference them from `--market-prices` when creating or updating plan prices.

```bash theme={null}
commet markets create \
  --name "Argentina" \
  --country-codes '["AR"]'

commet markets list
commet markets get --id pmg_argentina
commet markets update --id pmg_argentina --name "Southern Cone" --country-codes '["AR","BO","PY","UY"]'
commet markets delete --id pmg_argentina
```

## Webhooks

Create and test webhook endpoints.

**`commet webhooks create`**

Create a webhook endpoint.

```bash theme={null}
commet webhooks create \
  --url https://example.com/webhooks \
  --events '["subscription.activated","payment.received"]'
```

| Flag | Required | Description |
| - | - | - |
| `--url <url>` | Yes | Webhook URL |
| `--events <json>` | Yes | Events to subscribe to (JSON array) |
| `--description <desc>` | No | Webhook description |

> [!NOTE]
>
> For local development, use [`commet listen`](#setup) instead of creating a webhook endpoint.

```bash theme={null}
commet webhooks list                                 # List all webhook endpoints
commet webhooks list --limit 25 --cursor cur_xxx     # Paginate
commet webhooks delete --id whe_xxx                  # Delete endpoint
commet webhooks test --id whe_xxx                    # Send a test event
```

## Provisioning

Issue a fresh claim link for a headlessly provisioned organization that has not been claimed yet. The command uses that organization's API key; it cannot issue a link after a human has claimed the organization.

```bash theme={null}
commet provisioning create-claim-link \
  --idempotency-key claim-acme-2026-08-16
```

Use the same idempotency key when retrying the same request. Give the returned URL to the intended human owner; do not publish it or store it in source control.

## API Keys

Create and manage API keys.

```bash theme={null}
commet api-keys create --name "Production" --expires-in-days 365
commet api-keys list                                 # List all API keys
commet api-keys list --limit 25 --cursor cur_xxx     # Paginate
commet api-keys delete --id key_xxx                  # Delete an API key
```

| Flag | Required | Description |
| - | - | - |
| `--name <name>` | Yes (create) | API key name |
| `--expires-in-days <n>` | No | Expiration in days |

## Portal

Generate a portal URL for customer self-service.

```bash theme={null}
commet portal get-url --customer-id user_123
commet portal get-url --email user@acme.com
```

Provide either `--customer-id` or `--email`.

## Payouts

Manage payout bank accounts and request payouts. Payout commands require a live organization API key; sandbox keys return `payouts_not_available_in_sandbox`.

**`commet payouts request`**

Request a payout of available balance.

```bash theme={null}
commet payouts request --amount 50000 --description "Weekly payout"
```

| Flag | Required | Description |
| - | - | - |
| `--amount <n>` | Yes | Amount in cents (USD, minimum 1000) |
| `--description <desc>` | No | Payout description |

**`commet payouts add-bank-account`**

Add a destination bank account to the payout account.

```bash theme={null}
commet payouts add-bank-account \
  --account-number 000123456789 \
  --account-holder-name "Acme Inc." \
  --routing-number 110000000 \
  --account-type checking \
  --set-default true
```

| Flag | Required | Description |
| - | - | - |
| `--account-number <number>` | Yes | Bank account number |
| `--account-holder-name <name>` | Yes | Account holder name |
| `--routing-number <number>` | No | Routing number |
| `--account-type <type>` | No | `checking` or `savings` |
| `--set-default <bool>` | No | Set as default bank account |

## Test Clock

Control the sandbox test clock to simulate the passage of time.

> [!WARNING]
>
> **Sandbox only.** Test clock commands fail against live organizations.

**`commet test-clock advance`**

Move the test clock forward and process every billing deadline due before the target time.

```bash theme={null}
commet test-clock advance --advance-days 30
```

```bash theme={null}
commet test-clock advance --frozen-time 2026-07-01T00:00:00Z
```

| Flag | Required | Description |
| - | - | - |
| `--advance-days <n>` | One of `advance-days` / `frozen-time` | Days to move the clock forward |
| `--frozen-time <ts>` | One of `advance-days` / `frozen-time` | Absolute instant to move to (ISO 8601) |

```bash theme={null}
commet test-clock get # Get the current clock and latest run state
```

The former `commet test-clock process-billing` command is deprecated. `advance` now starts billing processing automatically.

## Quota

Manage quota allowances for quota-based features.

**`commet quota add`**

Add to a customer's quota allowance for a feature.

```bash theme={null}
commet quota add --feature-code api_calls --customer-id user_123 --count 100
```

| Flag | Required | Description |
| - | - | - |
| `--feature-code <code>` | Yes | Feature code |
| `--customer-id <id>` | One of `customer-id` / `external-id` | Customer ID |
| `--external-id <id>` | One of `customer-id` / `external-id` | Customer external ID |
| `--count <n>` | No | Amount to add. Default: `1` |
| `--idempotency-key <key>` | No | HTTP idempotency key for request deduplication |

```bash theme={null}
commet quota set --feature-code api_calls --customer-id user_123 --count 500    # Set exact allowance
commet quota remove --feature-code api_calls --customer-id user_123 --count 10  # Remove from allowance
commet quota get --customer-id user_123 --feature-code api_calls                # Get allowance for a feature
commet quota get-all --customer-id user_123                                     # Get all allowances
```

## Global Options

These flags work on every command:

| Flag | Description |
| - | - |
| `--output <format>` | `human` (default) or `agent` (JSON) |
| `--help` | Show help for any command |
| `--version` | Print CLI version |

Use `--output agent` for structured JSON output in scripts and CI pipelines:

```bash theme={null}
commet customers list --output agent | jq '.[0].id'
```

## CI/CD

Set `COMMET_API_KEY` as an environment variable. No `commet login` needed.

```yaml .github/workflows/billing.yml theme={null}
env:
  COMMET_API_KEY: ${{ secrets.COMMET_API_KEY }}
steps:
  - run: npx commet push --yes --output agent
```

```yaml .github/workflows/subscription.yml theme={null}
env:
  COMMET_API_KEY: ${{ secrets.COMMET_API_KEY }}
steps:
  - run: |
      npx commet subscriptions create \
        --customer-id user_123 \
        --plan-code pro \
        --billing-interval monthly \
        --output agent
```

## Configuration Files

| File | Created by | Purpose |
| - | - | - |
| `~/.commet/auth.json` | `commet login` | Global auth credentials |
| `.commet/config.json` | `commet link` | Project-to-organization link and auto-generated API key |
| `commet.config.ts` | `commet pull` | Generated billing config with types |

> [!NOTE]
>
> Run `commet <command> --help` for the full list of flags and options on any command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.