Command-line tool (CLI)
The openpromoter command-line tool for scripts and CI. It forwards webhook events to localhost for testing and installs the agent skill for you.
The CLI is published as openpromoter-cli and installs a command called openpromoter. It uses the same REST API and API keys as the SDK.
Install
npm install -g openpromoter-cli
openpromoter --help
Or run it without installing:
npx -y openpromoter-cli --help
Log in
openpromoter login --key op_live_… --url https://app.openpromoter.com
login checks the key, lists your programs and saves the URL and key to ~/.config/openpromoter/config.json (readable only by you). --url defaults to Cloud; self-hosters pass their APP_URL. In CI, set OPENPROMOTER_API_KEY and OPENPROMOTER_URL instead; when both are set they take precedence over the saved file.
Commands
| Command | What it does |
|---|---|
openpromoter programs |
List programs |
openpromoter stats --program <id> [--days 30] |
Revenue, commissions, clicks, signups, customers, MRR and amount owed |
openpromoter partners list --program <id> [--status <status>] |
List partners |
openpromoter partners invite --program <id> --email <email> --name <name> |
Invite and approve a partner |
openpromoter partners approve <partnerId> |
Approve a partner |
openpromoter partners pause <partnerId> |
Pause a partner |
openpromoter partners ban <partnerId> |
Ban a partner |
openpromoter commissions --program <id> [--status <status>] |
List commissions |
openpromoter payouts list --program <id> |
List payouts |
openpromoter payouts prepare --program <id> |
Prepare payouts. Approve them in the dashboard; the CLI cannot send money |
openpromoter ask --program <id> <question…> |
Ask a plain-language question |
openpromoter listen --forward-to <url> [--secret <secret>] |
Forward live events to a local URL with real webhook signatures |
openpromoter skill [--dir .] |
Install the agent skill for Claude Code and Cursor in a project |
List commands print a table; add --json for machine-readable output.
Forwarding events to localhost
openpromoter listen --forward-to http://localhost:4000/webhooks/openpromoter --secret whsec_local
listen polls GET /api/v1/events every two seconds, starting from now, and POSTs each new event to your URL with OpenPromoter-Signature and OpenPromoter-Event headers. The signature uses --secret (default whsec_local_listen), and your handler should verify with the same value. See Webhooks.
Installing the agent skill
openpromoter skill
writes .claude/skills/openpromoter/SKILL.md and .cursor/rules/openpromoter.mdc into the current project. Then ask your agent to "add an affiliate program to my app with OpenPromoter". See Install with an AI agent.
In CI
Store the key as a secret and keep its scopes narrow. A read key is enough for reports.
License
The CLI is MIT licensed. You can use it in any codebase. The OpenPromoter app itself is AGPL-3.0.