paddle

name

paddle

description

Interact with the Paddle Billing API (paddle.com) from the command line. Use when the user wants to manage a Paddle seller account — creating products, prices, subscriptions, customers, transactions, or discount codes — or when setting up Paddle for a new product, especially a Merchant-of-Record-backed macOS app with a free trial and licensing. Provides a `paddle` shell CLI with gh-style interactive authentication (`paddle auth login`), macOS Keychain credential storage, and sandbox/production environment switching. Triggers on mentions of Paddle, paddle.com, Merchant of Record for software, `paddle auth login`, creating Paddle products/prices/trials, or managing Paddle subscriptions from the terminal.

Paddle CLI

A thin, Keychain-backed shell wrapper around the Paddle Billing REST API. Ships a single executable at scripts/paddle.

When to use this skill

• The user wants to configure or inspect their Paddle seller account from the terminal — products, prices, trials, subscriptions, customers, transactions, discounts.
• The user says "set up a Paddle product", "create a Paddle price with a 30-day trial", "list my subscriptions", etc.
• The user needs to authenticate against Paddle (paddle auth login) or switch between sandbox and production environments.
• The user mentions Paddle specifically. (For generic payment/billing questions with no Paddle mention, do not invoke.)

Prerequisites

• macOS (uses the security command for Keychain storage).
• curl (built-in) and jq (brew install jq if missing — the CLI hard-fails with that hint).
• A Paddle sandbox account (free, immediate — does not require KYC approval).
• A Paddle API key, created at:
  • Sandbox: https://sandbox-vendors.paddle.com/authentication-v2
  • Production: https://vendors.paddle.com/authentication-v2

Invoking the CLI

The script lives at scripts/paddle inside this skill directory. Invoke it by its absolute path — do not assume it's on PATH unless the user has symlinked it.

# Resolve the absolute path once and reuse it:
PADDLE="$HOME/.claude/skills/paddle/scripts/paddle"
# ...or, when running from the dev checkout:
PADDLE="$HOME/Developments/paddle-skill/scripts/paddle"

"$PADDLE" auth status
"$PADDLE" products list

If the user wants paddle on their PATH, suggest:

mkdir -p ~/.local/bin
ln -sfn "$(pwd)/scripts/paddle" ~/.local/bin/paddle   # run from the skill dir
# then add ~/.local/bin to PATH in ~/.zshrc if not already

First-time setup (gh-style flow)

paddle auth login --env sandbox

This will:

1. Print the Paddle dashboard URL for API-key creation and offer to open it.
2. Prompt for the key (hidden input).
3. Verify the key by calling GET /event-types.
4. Store the key in the macOS Keychain under service paddle-cli, account sandbox (or production).
5. If no default env is set yet, set the login'd env as the default.

Repeat with --env production once the user's Paddle KYC is approved. Both keys can be stored simultaneously; switch with paddle env sandbox|production or per-call with paddle --env production <cmd>.

Common operations

# Auth & env
paddle auth status
paddle auth logout --env sandbox
paddle env production                    # set default env

# Products
paddle products list status=active
paddle products get pro_01abc...
paddle products create '{"name":"Percev Pro","tax_category":"standard"}'

# Prices (with 30-day trial)
paddle prices create '{
  "product_id": "pro_01abc...",
  "description": "Yearly",
  "billing_cycle": {"interval":"year","frequency":1},
  "trial_period": {"interval":"day","frequency":30},
  "unit_price": {"amount":"7900","currency_code":"USD"}
}'

# Subscriptions
paddle subscriptions list customer_id=ctm_...
paddle subscriptions cancel sub_01... effective_from=next_billing_period

# Raw escape hatch for anything the wrappers don't cover
paddle api GET  /reports
paddle api POST /notification-settings '{"description":"dev","destination":"https://example.com/hook","subscribed_events":["transaction.completed"]}'

# One-off against production without changing default
paddle --env production products list

List commands accept filters as either key=value or --key value pairs; they map directly to Paddle API query parameters. See paddle help and the Paddle API reference for fields.

Rules of engagement

• Default to sandbox. If the user has not explicitly said "production" or "live", run against sandbox. Production mutations can create real charges, emails, and tax records.
• Never print API keys. The CLI reads them from Keychain; do not echo, cat, or pass them as CLI arguments. If you need to pass a key to another tool, pipe via paddle auth helpers or read via security find-generic-password inline.
• Prefer the resource subcommands over paddle api when one exists — they do argument validation and pretty-print. Fall back to paddle api METHOD PATH [JSON] only for endpoints without a subcommand.
• Dry-run destructive work. Before subscriptions cancel, products update, or bulk operations, show the user the target object (paddle <resource> get <id>) and confirm.
• Confirm before logout. paddle auth logout removes the key from Keychain permanently; a new paddle auth login is required to restore.

Dependencies referenced by this skill

• scripts/paddle — the executable. POSIX-ish bash 3.2-compatible.

Links

• Paddle Billing API: https://developer.paddle.com/api-reference/overview
• Sandbox onboarding: https://developer.paddle.com/build/tools/sandbox
• MoR overview: https://www.paddle.com/merchant-of-record