Polar CLI

Unofficial CLI for Polar with full API parity. Optimized for both developers and AI agents.

When to use

Use this CLI when you need to:

• Manage Polar resources (products, customers, subscriptions, orders, etc.)
• Create or inspect checkouts and checkout links
• Issue, validate, or manage license keys
• Ingest events or query usage-based billing meters
• Set up webhooks
• Script or automate Polar workflows from the terminal

Install

npm install -g @miketromba/polar-cli

The CLI is also available via npx @miketromba/polar-cli, or install with yarn/pnpm/bun.

Authentication

# Interactive login (token is stored locally)
polar auth login --token <access-token>

# Or set the environment variable (preferred for CI/scripts/agents)
export POLAR_ACCESS_TOKEN=polar_at_xxx

Get an access token at https://polar.sh/settings.

Check auth status:

polar auth status

Command grammar

All commands follow this pattern:

polar <resource> <action> [id] [--flags]

Examples:

polar products list
polar customers get <id>
polar subscriptions create --customer-id <id> --product-id <id>
polar checkouts create --products <product-id>
polar webhooks delete <id> --yes

Run polar --help for all resources. Run polar <resource> --help for actions and examples.

Output formats

The CLI auto-detects the environment:

Override with -o <format>:

Parsing compact output

Compact format is optimized for AI agents:

products 1-5/42 page=1
  [1] id=prod_123 name="Pro Plan" isRecurring=true prices=1
  [2] id=prod_456 name="Starter" isRecurring=true prices=1
next: polar products list --page 2 --limit 5

Field selection

polar customers list --fields id,email,name
polar products get <id> --detail    # Full detail view

Common workflows

List and filter resources

polar products list
polar products list --query "Pro" --limit 5
polar customers list --email [email protected]
polar subscriptions list --active --product-id <id>
polar orders list --customer-id <id> --output json

Create resources

polar customers create --email [email protected] --name "Jane Doe"
polar products create --name "Pro Plan" --prices '[{"amount":2999,"currency":"usd","recurringInterval":"month"}]'
polar checkouts create --products <product-id> --customer-email [email protected]
polar discounts create --name "20% Off" --type percentage --amount 20 --duration once
polar webhooks create --url https://example.com/hook --events order.created,subscription.created

Update and delete

polar products update <id> --name "Enterprise Plan"
polar customers update <id> --name "Jane Smith"
polar customers delete <id> --yes    # --yes required for destructive actions

License keys

polar license-keys list
polar license-keys validate --key XXXX-XXXX --organization-id <org-id>
polar license-keys activate --key XXXX-XXXX --organization-id <org-id> --label "Prod Server"

Usage-based billing

polar meters list
polar events ingest --events '[{"name":"api_call","externalCustomerId":"user_123"}]'
polar metrics get --start-date 2025-01-01 --end-date 2025-01-31 --interval month

Pagination

polar products list --limit 50 --page 2
polar products list --first 3         # Shorthand: --limit 3 --page 1
polar products list --all             # Fetch all pages

Pipe patterns

# Get all product IDs
polar products list -o id

# Count active subscriptions
polar subscriptions list --active -o count

# Export customers as JSON
polar customers list --all -o json > customers.json

# Pipe to jq
polar orders list -o jsonl | jq '.totalAmount'

Environment variables

Key global flags

Resources

For the full list of resources and their operations, see [reference.md](reference.md).

Official Polar documentation

For deeper understanding of Polar platform concepts, API behaviors, scopes, webhook events, or feature guides, fetch the official docs index:

https://polar.sh/docs/llms.txt

This is a machine-readable index of all Polar documentation. Use it when you need to:

• Understand how a Polar feature works (e.g., usage-based billing, seat-based pricing, trials)
• Check required API scopes for an operation
• Look up webhook event payloads and lifecycle
• Find guides for specific workflows (e.g., checkout sessions, license key validation)
• Verify API behavior or constraints that the CLI wraps

Fetch the index, find the relevant doc URL, then fetch that page for full details.