Commet
  • Pricing
Log InTry out
Introduction

Quickstart

Learn

Resources

SDK ReferenceAPI VersioningError HandlingTestingCLI

Plugins

Better Auth
DocumentationKnowledge BaseBuild with AIAPI ReferenceWebhooks

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 add -g commet
npm install -g commet
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.

commet login

In CI, set COMMET_API_KEY as an environment variable instead.

PrioritySourceHow to set
1 (highest)COMMET_API_KEY env varexport COMMET_API_KEY=ck_...
2Project API keyAuto-generated by commet link (stored in .commet/config.json)
3 (lowest)Saved credentialscommet login
commet logout     # Remove stored credentials

Setup

commet link

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

commet link
commet link --org acme       # By slug or ID
commet link --clear          # Unlink project
FlagRequiredDescription
--org <slug-or-id>NoOrganization slug or ID. Skips interactive selection
--clearNoUnlink project from its organization

commet pull

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

commet pull
commet pull --dry-run        # Preview changes without writing
commet pull --yes            # Skip confirmation
FlagRequiredDescription
--dry-runNoShow what would change without writing any files
-y, --yesNoSkip 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.

commet push
commet push --dry-run        # Preview what would change on remote
commet push --yes            # Push without confirmation
FlagRequiredDescription
--dry-runNoShow what would change without pushing
-y, --yesNoSkip confirmation prompt

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.

commet create
commet create myapp -t metered --org acme -y
commet create --list              # List available templates
FlagRequiredDescription
-t, --template <name>NoTemplate: fixed, seats, metered, credits, balance-ai, balance-fixed
--org <slug>NoSandbox organization slug or ID
--skillsNoInstall agent skills
--no-skillsNoSkip agent skills installation
-y, --yesNoAccept defaults for optional prompts
--ref <ref>NoGit ref to fetch templates from. Default: main

commet listen

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

commet listen 3000

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

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:

commet listen 3000 --events invoice.paid,subscription.activated
FlagRequiredDescription
<url>YesTarget URL: port (3000), host:port, or full URL
--events <types>NoComma-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.

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.

commet customers create --email user@acme.com --id user_123
commet customers create \
  --email billing@corp.com \
  --full-name "Acme Corp" \
  --metadata '{"plan":"enterprise"}'
FlagRequiredDescription
--email <email>YesBilling email
--id <id>NoCustom customer ID
--full-name <name>NoFull name
--domain <domain>NoDomain
--website <url>NoWebsite URL
--timezone <tz>NoTimezone
--language <lang>NoLanguage code
--industry <industry>NoIndustry
--metadata <json>NoMetadata as JSON object
--address <json>NoAddress as JSON: {line1, city, postalCode, country}
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 --start-date 2026-01-01 --end-date 2026-06-01  # Filter by date
commet customers list --search "acme"               # Search customers
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.

commet subscriptions create \
  --customer-id user_123 \
  --plan-code pro \
  --billing-interval monthly
commet subscriptions create \
  --customer-id user_123 \
  --plan-id plan_xxx \
  --billing-interval yearly \
  --initial-seats '{"team_member":5}' \
  --skip-trial true
FlagRequiredDescription
--customer-id <id>YesCustomer ID
--plan-code <code>One of plan-code / plan-idPlan code
--plan-id <id>One of plan-code / plan-idPlan ID
--billing-interval <interval>Noweekly, monthly, quarterly, yearly, one_time
--initial-seats <json>NoInitial seats as JSON: {featureCode: count}
--skip-trial <bool>NoSkip trial period
--name <name>NoSubscription name
--start-date <date>NoStart date (ISO 8601)
--success-url <url>NoRedirect URL after successful checkout

commet subscriptions cancel

Cancel a subscription. Cancels at period end by default.

commet subscriptions cancel --id sub_xxx
commet subscriptions cancel --id sub_xxx --immediate true --reason "Customer requested"
FlagRequiredDescription
--id <id>YesSubscription ID
--reason <reason>NoCancellation reason
--immediate <bool>NoCancel immediately instead of at period end
commet subscriptions get-active --customer-id user_123           # Get active subscription
commet subscriptions uncancel --id sub_xxx                       # Revert pending cancellation
commet subscriptions change-plan --id sub_xxx --new-plan-id plan_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 list --limit 25 --cursor cur_xxx                # Paginate
commet subscriptions preview-change --id sub_xxx --plan-id plan_xxx --billing-interval yearly  # Preview proration
commet subscriptions activate-addon --id sub_xxx --addon-id addon_xxx
commet subscriptions deactivate-addon --id sub_xxx --addon-id addon_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 cp_xxx

Plans

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

commet plans create

Create a plan.

commet plans create --name "Pro" --code pro
commet plans create \
  --name "Developer" \
  --code developer \
  --consumption-model metered \
  --is-public true \
  --block-on-exhaustion true
FlagRequiredDescription
--name <name>YesPlan name
--code <code>YesPlan code
--description <desc>NoPlan description
--consumption-model <model>Nometered, credits, or balance
--is-public <bool>NoWhether plan is publicly visible
--is-free <bool>NoWhether plan is free
--block-on-exhaustion <bool>NoBlock usage when balance/credits exhausted
--plan-group-id <id>NoPlan group ID
--metadata <json>NoMetadata as JSON object

commet plans add-feature

Add a feature to a plan with pricing and limits.

commet plans add-feature \
  --plan-id plan_xxx \
  --feature-id feat_xxx \
  --included-amount 1000 \
  --overage-enabled true \
  --overage-unit-price 100
commet plans add-feature \
  --plan-id plan_xxx \
  --feature-id feat_xxx \
  --pricing-mode ai_model \
  --margin 30
FlagRequiredDescription
--plan-id <id>YesPlan ID
--feature-id <id>YesFeature ID
--enabled <bool>NoWhether feature is enabled
--included-amount <n>NoIncluded usage amount
--unlimited <bool>NoUnlimited usage
--overage-enabled <bool>NoEnable overage billing
--overage-unit-price <n>NoOverage price per unit (fixed pricing)
--pricing-mode <mode>Nofixed or ai_model
--margin <n>NoMargin percentage (ai_model pricing)
--credits-per-unit <n>NoCredits per unit

commet plans add-price

Add a price to a plan.

commet plans add-price \
  --plan-id plan_xxx \
  --billing-interval monthly \
  --price 2900
commet plans add-price \
  --plan-id plan_xxx \
  --billing-interval yearly \
  --price 29000 \
  --trial-days 14 \
  --intro-offer-enabled true \
  --intro-offer-discount-type percentage \
  --intro-offer-discount-value 50 \
  --intro-offer-duration-cycles 3
FlagRequiredDescription
--plan-id <id>YesPlan ID
--billing-interval <interval>Yesweekly, monthly, quarterly, yearly, one_time
--price <n>YesPrice in cents
--trial-days <n>NoTrial period in days
--is-default <bool>NoSet as default price
--included-balance <n>NoIncluded balance amount
--included-credits <n>NoIncluded credits amount
--intro-offer-enabled <bool>NoEnable intro offer
--intro-offer-discount-type <type>Nopercentage or amount
--intro-offer-discount-value <n>NoDiscount value
--intro-offer-duration-cycles <n>NoDuration in billing cycles
commet plans list                                    # List all plans
commet plans list --limit 25 --cursor cur_xxx        # Paginate
commet plans list --include-private true              # Include private plans
commet plans get --id pro                            # Get plan details
commet plans update --id plan_xxx --name "Pro Plus" --description "For growing teams" --metadata '{}' --is-public true  # Update a plan
commet plans delete --id plan_xxx                    # Delete a plan
commet plans set-visibility --id plan_xxx --is-public false
commet plans update-feature --plan-id plan_xxx --feature-id feat_xxx --included-amount 2000
commet plans remove-feature --plan-id plan_xxx --feature-id feat_xxx
commet plans update-price --plan-id plan_xxx --price-id price_xxx --price 3900
commet plans delete-price --plan-id plan_xxx --price-id price_xxx
commet plans set-default-price --plan-id plan_xxx --price-id price_xxx

Regional prices

Set local currency overrides for a price.

commet plans set-regional-prices \
  --plan-id plan_xxx \
  --price-id price_xxx \
  --overrides '[{"currency":"EUR","price":2700},{"currency":"BRL","price":14900}]'
commet plans delete-regional-prices --plan-id plan_xxx --price-id price_xxx

Features

Manage the organization's feature catalog.

commet features create

Create a feature.

commet features create --code api_calls --name "API Calls" --type usage --unit-name calls
FlagRequiredDescription
--code <code>YesFeature code
--name <name>YesFeature name
--type <type>Yesboolean, usage, or seats
--description <desc>NoFeature description
--unit-name <name>NoUnit name for metered features
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.

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
commet feature-access can-use --customer-id user_123 --code api_calls   # Check if customer can use one more unit

Seats

Manage seat allocations for per-seat billing.

commet seats add

Add seats for a customer.

commet seats add --customer-id user_123 --feature-code team_member
commet seats add --customer-id user_123 --feature-code team_member --count 5
FlagRequiredDescription
--customer-id <id>YesCustomer ID
--feature-code <code>YesFeature code
--count <n>NoNumber of seats to add. Default: 1
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.

commet usage track --feature api_calls --customer-id user_123 --value 1
commet usage track \
  --feature gpt-4o \
  --customer-id user_123 \
  --model gpt-4o \
  --input-tokens 500 \
  --output-tokens 150 \
  --cache-read-tokens 200
FlagRequiredDescription
--feature <code>YesFeature code
--customer-id <id>YesCustomer ID
--value <n>One of value / modelUsage value (standard tracking)
--model <model>One of value / modelAI model name (token tracking)
--input-tokens <n>NoInput tokens (model tracking)
--output-tokens <n>NoOutput tokens (model tracking)
--cache-read-tokens <n>NoCache read tokens (model tracking)
--cache-write-tokens <n>NoCache write tokens (model tracking)
--idempotency-key <key>NoPrevents duplicate events. Max 256 characters
--timestamp <ts>NoEvent timestamp (ISO 8601)
--properties <json>NoEvent properties as JSON object
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.

commet addons create \
  --name "Extra Storage" \
  --base-price 500 \
  --feature-id feat_xxx \
  --consumption-model metered
commet addons create \
  --name "Priority Support" \
  --base-price 2900 \
  --feature-id feat_xxx \
  --consumption-model boolean
FlagRequiredDescription
--name <name>YesAddon name
--base-price <n>YesBase price in cents
--feature-id <id>YesFeature ID
--consumption-model <model>Yesboolean, metered, credits, or balance
--description <desc>NoAddon description
--included-units <n>NoIncluded units (metered)
--overage-rate <n>NoOverage rate (metered/balance)
--credit-cost <n>NoCredit cost (credits)
commet addons list                                   # List all addons
commet addons list --limit 25 --cursor cur_xxx       # Paginate
commet addons get --id addon_xxx                     # Get addon details
commet addons update --id addon_xxx --name "Extra Storage Pro" --description "100GB extra" --base-price 900 --included-units 100 --overage-rate 10  # Update an addon
commet addons delete --id addon_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.

commet credit-packs create --name "500 Credits" --credits 500 --price 4900
commet credit-packs list                             # List all credit packs
commet credit-packs update --id cp_xxx --price 3900  # Update a credit pack
commet credit-packs delete --id cp_xxx               # Delete a credit pack
FlagRequiredDescription
--name <name>Yes (create)Credit pack name
--credits <n>Yes (create)Number of credits
--price <n>Yes (create)Price in cents
--description <desc>NoCredit pack description
--is-active <bool>NoWhether credit pack is active

Plan Groups

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

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 pg_xxx                   # Get plan group details
commet plan-groups add-plan --id pg_xxx --plan-id plan_xxx --sort-order 1
commet plan-groups remove-plan --id pg_xxx --plan-id plan_xxx
commet plan-groups reorder-plans --id pg_xxx --plan-ids '["plan_a","plan_b","plan_c"]'
commet plan-groups update --id pg_xxx --name "Updated Plans" --description "New description" --is-public false
commet plan-groups delete --id pg_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.

commet invoices create-adjustment \
  --customer-id cus_xxx \
  --amount -500 \
  --description "Courtesy credit"
FlagRequiredDescription
--customer-id <id>YesCustomer ID
--amount <n>YesAmount in cents. Negative for credit
--description <desc>NoAdjustment description
--metadata <json>NoMetadata as JSON object
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)

Transactions

List transactions, process refunds, and retry failed payments.

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

Promo Codes

Create and manage discount codes.

commet promo-codes create

Create a promo code.

commet promo-codes create \
  --code SUMMER25 \
  --discount-type percentage \
  --discount-value 25 \
  --duration-cycles 3 \
  --max-redemptions 100
commet promo-codes create \
  --code FLAT10 \
  --discount-type amount \
  --discount-value 1000 \
  --plan-ids '["plan_pro","plan_team"]' \
  --expires-at 2026-12-31
FlagRequiredDescription
--code <code>YesPromo code string
--discount-type <type>Yespercentage or amount
--discount-value <n>YesDiscount value
--duration-cycles <n>NoDuration in billing cycles
--max-redemptions <n>NoMaximum number of redemptions
--expires-at <date>NoExpiration date (ISO 8601)
--plan-ids <json>NoRestrict to specific plan IDs (JSON array)
commet promo-codes list                              # List all promo codes
commet promo-codes list --limit 25 --cursor cur_xxx  # Paginate
commet promo-codes get --id promo_xxx                # Get promo code details
commet promo-codes update --id promo_xxx --active false --max-redemptions 50 --expires-at 2026-12-31 --plan-ids '["plan_pro"]'  # Update

Webhooks

Create and test webhook endpoints.

commet webhooks create

Create a webhook endpoint.

commet webhooks create \
  --url https://example.com/webhooks \
  --events '["subscription.activated","payment.received"]'
FlagRequiredDescription
--url <url>YesWebhook URL
--events <json>YesEvents to subscribe to (JSON array)
--description <desc>NoWebhook description

For local development, use commet listen instead of creating a webhook endpoint.

commet webhooks list                                 # List all webhook endpoints
commet webhooks list --limit 25 --cursor cur_xxx     # Paginate
commet webhooks delete --id wh_xxx                   # Delete endpoint
commet webhooks test --id wh_xxx                     # Send a test event

API Keys

Create and manage API keys.

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
FlagRequiredDescription
--name <name>Yes (create)API key name
--expires-in-days <n>NoExpiration in days

Portal

Generate a portal URL for customer self-service.

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, request payouts, and complete account verification.

commet payouts request

Request a payout of available balance.

commet payouts request --amount 50000 --description "Weekly payout"
FlagRequiredDescription
--amount <n>YesAmount in cents (USD, minimum 1000)
--description <desc>NoPayout description

commet payouts add-bank-account

Add a destination bank account to the payout account.

commet payouts add-bank-account \
  --account-number 000123456789 \
  --account-holder-name "Acme Inc." \
  --routing-number 110000000 \
  --account-type checking \
  --set-default true
FlagRequiredDescription
--account-number <number>YesBank account number
--account-holder-name <name>YesAccount holder name
--routing-number <number>NoRouting number
--account-type <type>Nochecking or savings
--set-default <bool>NoSet as default bank account

commet payouts complete-verification

Provision the payout account with the full KYC payload.

commet payouts complete-verification \
  --email owner@acme.com \
  --business-type company \
  --business-url https://acme.com \
  --document-url https://files.acme.com/incorporation.pdf \
  --bank '{"accountNumber":"000123456789","accountHolderName":"Acme Inc."}' \
  --company '{"name":"Acme Inc.","taxId":"12-3456789"}'
FlagRequiredDescription
--email <email>YesContact email
--business-type <type>Yesindividual or company
--business-url <url>YesBusiness website URL
--document-url <url>YesIdentity document URL
--bank <json>YesBank account as JSON: {accountNumber, accountHolderName, ...}
--individual <json>NoIndividual KYC details (JSON, individual businesses)
--company <json>NoCompany KYC details (JSON, company businesses)

Test Clock

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

Sandbox only. Test clock commands fail against live organizations.

commet test-clock advance

Move the test clock forward.

commet test-clock advance --advance-days 30
commet test-clock advance --frozen-time 2026-07-01T00:00:00Z
FlagRequiredDescription
--advance-days <n>One of advance-days / frozen-timeDays to move the clock forward
--frozen-time <ts>One of advance-days / frozen-timeAbsolute instant to move to (ISO 8601)
commet test-clock get                # Get the current test clock state
commet test-clock process-billing    # Run billing cycles due at the simulated time

Quota

Manage quota allowances for quota-based features.

commet quota add

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

commet quota add --feature-code api_calls --customer-id user_123 --count 100
FlagRequiredDescription
--feature-code <code>YesFeature code
--customer-id <id>One of customer-id / external-idCustomer ID
--external-id <id>One of customer-id / external-idCustomer external ID
--count <n>NoAmount to add. Default: 1
--idempotency-key <key>NoIdempotency key for deduplication
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:

FlagDescription
--output <format>human (default) or agent (JSON)
--helpShow help for any command
--versionPrint CLI version

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

commet customers list --output agent | jq '.[0].id'

CI/CD

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

env:
  COMMET_API_KEY: ${{ secrets.COMMET_API_KEY }}
steps:
  - run: npx commet push --yes --output agent
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

FileCreated byPurpose
~/.commet/auth.jsoncommet loginGlobal auth credentials
.commet/config.jsoncommet linkProject-to-organization link and auto-generated API key
commet.config.tscommet pullGenerated billing config with types

Run commet <command> --help for the full list of flags and options on any command.

How is this guide?

Testing

Test safely with sandbox environment

Better Auth

Better Auth Plugin for Billing and Subscriptions using Commet

On this page

Install
Authentication
Setup
Customers
Subscriptions
Plans
Regional prices
Features
Feature Access
Seats
Usage
Addons
Credit Packs
Plan Groups
Invoices
Transactions
Promo Codes
Webhooks
API Keys
Portal
Payouts
Test Clock
Quota
Global Options
CI/CD
Configuration Files