polar

name	polar
description	Use the Polar CLI to manage products, subscriptions, customers, orders, checkouts, license keys, webhooks, and other resources on the Polar (polar.sh) platform. Use when the user asks to interact with Polar, manage SaaS billing, create checkouts, issue license keys, or query monetization data from the command line.

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:

Context	Default format	Description
TTY (interactive)	table	Human-readable columns with color
Piped / non-TTY	compact	key=value one-liners, minimal tokens

Override with -o <format>:

Format	Flag	Use case
compact	-o compact	AI agents, scripting
json	-o json	Programmatic consumption
jsonl	-o jsonl	Streaming, jq pipelines
csv	-o csv	Export, spreadsheets
tsv	-o tsv	Unix tools (cut, awk)
id	-o id	Pipe IDs to other commands
count	-o count	"How many?" queries
table	-o table	Human-readable

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 [e-mail]
polar subscriptions list --active --product-id <id>
polar orders list --customer-id <id> --output json

Create resources

polar customers create --email [e-mail] --name "Jane Doe"
polar products create --name "Pro Plan" --prices '[{"amount":2999,"currency":"usd","recurringInterval":"month"}]'
polar checkouts create --products <product-id> --customer-email [e-mail]
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

Variable	Purpose
POLAR_ACCESS_TOKEN	Access token (overrides stored credential)
POLAR_ORGANIZATION_ID	Default organization ID
POLAR_SERVER	production or sandbox
POLAR_OUTPUT	Default output format

Key global flags

Flag	Short	Description
--output <format>	-o	Output format
--fields <list>	-f	Comma-separated field selection
--detail	-d	Full detail view
--org <id>		Organization ID override
--yes	-y	Skip confirmation prompts
--quiet	-q	Data only, no hints or headers
--server <name>	-s	production or sandbox

Resources

For the full list of resources and their operations, see 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.