Every Lemon Squeezy resource, plus a local SQLite mirror that surfaces MRR, churn, license seats, and discount-campaign pace no other LS tool ships.
Lemon Squeezy's official SDKs are libraries, not CLIs, and the dashboard is a click-walk per store. This CLI mirrors all 19 LS resources to local SQLite with offline FTS5 and cross-entity SQL, then layers transcendence commands — revenue-snapshot, mrr-trend, churn-watch, dunning-alert, license-rollup, refund-cascade, campaign-watch, webhook-audit — that combine entities no single endpoint returns. Built for indie SaaS founders and license-key sellers who live in the LS state machine.
Authentication
Lemon Squeezy uses HTTP Bearer auth. Create an API key at https://app.lemonsqueezy.com/settings/api, then export LEMONSQUEEZY_API_KEY=<your-key>. Verify with lemonsqueezy-pp-cli doctor.
Quick Start
# Verify the binary loads and shows expected env vars before hitting the API.
lemonsqueezy-pp-cli doctor --dry-run
# Pull the core surface into local SQLite so the transcendence commands have data to work with.
lemonsqueezy-pp-cli sync --resources stores,products,variants,subscriptions,orders,customers
# Get a one-number rollup of 30-day + lifetime revenue, refund-adjusted from local orders.
lemonsqueezy-pp-cli revenue-snapshot --json
# List subscriptions that flipped into past_due/unpaid/cancelled in the last 7 days with dollar exposure.
lemonsqueezy-pp-cli churn-watch --since 7d --json
Unique Features
These capabilities aren't available in any other tool for this API.
Revenue + churn signal
-
revenue-snapshot — Point-in-time revenue rollup combining LS's denormalized 30-day/lifetime store counters with refund-adjusted net from local orders.
Reach for this when you want one number for 'how is the store doing right now' without walking every order through the API.
lemonsqueezy-pp-cli revenue-snapshot --agent
-
mrr-trend — Weekly MRR over a sliding window, classified as new / renewal / refunded with a week-over-week net delta.
Pick this over a raw list-subscriptions call when you need to show how MRR moved week-over-week, not just where it stands today.
lemonsqueezy-pp-cli mrr-trend --weeks 12 --json
-
churn-watch — Lists subscriptions that flipped to past_due/unpaid/cancelled/expired in a window, with customer email and dollar exposure per row.
Reach for this on Monday-morning sweeps to see what changed since Friday — beats clicking through the dashboard's status filters.
lemonsqueezy-pp-cli churn-watch --since 7d --json
-
dunning-alert — Lists subscription-invoices with status=failed whose parent subscription is still active or past_due — the recoverable window.
Use this to find subs whose latest renewal failed but who haven't churned yet — the window where a Slack ping or grace email recovers revenue.
lemonsqueezy-pp-cli dunning-alert --json
License + refund ops
-
license-rollup — Per-variant and per-key activation statistics joined across license-keys, license-key-instances, and variants.
Reach for this when you need to surface piracy-shaped seat distributions or just answer 'how many keys are active per variant'.
lemonsqueezy-pp-cli license-rollup --json --select keys
-
refund-cascade — Given a refunded order ID, walks order → order-items → license-keys → instances, then optionally disables the keys via --apply.
Use this after a refund hits, to make sure the buyer's license keys actually get disabled instead of staying active.
lemonsqueezy-pp-cli refund-cascade order_3aBc --dry-run --json
Campaign + integration ops
-
campaign-watch — Per discount code: redemptions used vs cap, redemption velocity over last 24h, projected sellout time at current pace (needs >=6h of redemption activity to stabilise).
Run this during a capped sale (Founding-Member tier, Early Access) to know when a tier will sell out so you can expire the code before overselling.
lemonsqueezy-pp-cli campaign-watch FOUNDING-LIFETIME FOUNDING-2YR FOUNDING-1YR --json
-
webhook-audit — Cross-store webhook coverage matrix grouped by URL host, flagging stale destinations (localhost, ngrok, *.test, *.local).
Reach for this to catch orphaned webhooks pointing at last week's ngrok URL before they cause a missed event in production.
lemonsqueezy-pp-cli webhook-audit --json
Recipes
Monday-morning revenue + churn sweep
lemonsqueezy-pp-cli sync --resources stores,subscriptions,subscription-invoices,orders --since 14d && lemonsqueezy-pp-cli revenue-snapshot --json && lemonsqueezy-pp-cli churn-watch --since 7d --json
Refreshes the local mirror, then prints the revenue rollup and the past-week churn delta — the ritual that replaces the dashboard click-walk.
Find recoverable failed renewals
lemonsqueezy-pp-cli dunning-alert --json --select rows.customer_email,rows.amount_usd
Lists every failed invoice whose subscription is still active or past_due — the dollar-recoverable window before the customer churns.
Refund cascade for an order
lemonsqueezy-pp-cli refund-cascade order_3aBc --apply --json
Walks the order → order-items → license-keys chain and disables every key tied to the refund. Drop --apply for a dry preview.
Track a capped Founding-Member sale
lemonsqueezy-pp-cli sync --resources discounts,discount-redemptions && lemonsqueezy-pp-cli campaign-watch FOUNDING-LIFETIME FOUNDING-2YR FOUNDING-1YR --json
Live capacity + redemption velocity per tier with sellout projection — run hourly during a launch to expire codes before overselling.
Webhook coverage audit
lemonsqueezy-pp-cli sync --resources webhooks && lemonsqueezy-pp-cli webhook-audit --json --select hosts.url,hosts.stale,hosts.event_count
Groups every webhook across every store by URL host, flags localhost/ngrok/*.test destinations so orphans don't break production.
Usage
Run lemonsqueezy-pp-cli --help for the full command reference and flag list.
Commands
affiliates
Manage affiliates
lemonsqueezy-pp-cli affiliates get - Lemon Squeezy Retrieve an affiliatelemonsqueezy-pp-cli affiliates list - Lemon Squeezy List all affiliates
checkouts
Manage checkouts
lemonsqueezy-pp-cli checkouts create - Lemon Squeezy Create a checkoutlemonsqueezy-pp-cli checkouts get - Lemon Squeezy Retrieve a checkoutlemonsqueezy-pp-cli checkouts list - Lemon Squeezy List all checkouts
customers
Manage customers
lemonsqueezy-pp-cli customers get - Lemon Squeezy Retrieve a customerlemonsqueezy-pp-cli customers list - Lemon Squeezy List all customers
discount-redemptions
Manage discount redemptions
lemonsqueezy-pp-cli discount-redemptions get - Lemon Squeezy Retrieve a discount redemptionlemonsqueezy-pp-cli discount-redemptions list - Lemon Squeezy List all discount redemptions
discounts
Manage discounts
lemonsqueezy-pp-cli discounts create - Lemon Squeezy Create a discountlemonsqueezy-pp-cli discounts delete - Lemon Squeezy Delete a discountlemonsqueezy-pp-cli discounts get - Lemon Squeezy Retrieve a discountlemonsqueezy-pp-cli discounts list - Lemon Squeezy List all discounts
files
Manage files
lemonsqueezy-pp-cli files get - Lemon Squeezy Retrieve a filelemonsqueezy-pp-cli files list - Lemon Squeezy List all files
health
Manage health
lemonsqueezy-pp-cli health - Lemon Squeezy Health
license-key-instances
Manage license key instances
lemonsqueezy-pp-cli license-key-instances get - Lemon Squeezy Retrieve a license key instancelemonsqueezy-pp-cli license-key-instances list - Lemon Squeezy List all license key instances
license-keys
Manage license keys
lemonsqueezy-pp-cli license-keys get - Lemon Squeezy Retrieve a license keylemonsqueezy-pp-cli license-keys list - Lemon Squeezy List all license keys
order-items
Manage order items
lemonsqueezy-pp-cli order-items get - Lemon Squeezy Retrieve an order itemlemonsqueezy-pp-cli order-items list - Lemon Squeezy List all order items
orders
Manage orders
lemonsqueezy-pp-cli orders get - Lemon Squeezy Retrieve an orderlemonsqueezy-pp-cli orders list - Lemon Squeezy List all orders
prices
Manage prices
lemonsqueezy-pp-cli prices get - Lemon Squeezy Retrieve a pricelemonsqueezy-pp-cli prices list - Lemon Squeezy List all prices
products
Manage products
lemonsqueezy-pp-cli products get - Lemon Squeezy Retrieve a productlemonsqueezy-pp-cli products list - Lemon Squeezy List all products
stores
Manage stores
lemonsqueezy-pp-cli stores get - Lemon Squeezy Retrieve a storelemonsqueezy-pp-cli stores list - Lemon Squeezy List all stores
subscription-invoices
Manage subscription invoices
lemonsqueezy-pp-cli subscription-invoices get - Lemon Squeezy Retrieve a subscription invoicelemonsqueezy-pp-cli subscription-invoices list - Lemon Squeezy List all subscription invoices
subscription-items
Manage subscription items
lemonsqueezy-pp-cli subscription-items get - Lemon Squeezy Retrieve a subscription itemlemonsqueezy-pp-cli subscription-items list - Lemon Squeezy List all subscription itemslemonsqueezy-pp-cli subscription-items update - Lemon Squeezy Update a subscription item
subscriptions
Manage subscriptions
lemonsqueezy-pp-cli subscriptions delete - Lemon Squeezy Cancel a Subscriptionlemonsqueezy-pp-cli subscriptions get - Lemon Squeezy Retrieve a subscriptionlemonsqueezy-pp-cli subscriptions list - Lemon Squeezy List all subscriptionslemonsqueezy-pp-cli subscriptions update - Lemon Squeezy Update a subscription
usage-records
Manage usage records
lemonsqueezy-pp-cli usage-records create - Lemon Squeezy Create a usage recordlemonsqueezy-pp-cli usage-records get - Lemon Squeezy Retrieve a usage-recordlemonsqueezy-pp-cli usage-records list - Lemon Squeezy List all usage records
users
Manage users
lemonsqueezy-pp-cli users - Lemon Squeezy Retrieve the authenticated user
variants
Manage variants
lemonsqueezy-pp-cli variants get - Lemon Squeezy Retrieve a variantlemonsqueezy-pp-cli variants list - Lemon Squeezy List all variants
webhooks
Manage webhooks
lemonsqueezy-pp-cli webhooks create - Lemon Squeezy Create a webhooklemonsqueezy-pp-cli webhooks delete - Lemon Squeezy Delete a webhooklemonsqueezy-pp-cli webhooks get - Lemon Squeezy Retrieve a webhooklemonsqueezy-pp-cli webhooks list - Lemon Squeezy List all webhookslemonsqueezy-pp-cli webhooks update - Lemon Squeezy Update a webhook
Output Formats
# Human-readable table (default in terminal, JSON when piped)
lemonsqueezy-pp-cli affiliates list
# JSON for scripting and agents
lemonsqueezy-pp-cli affiliates list --json
# Filter to specific fields
lemonsqueezy-pp-cli affiliates list --json --select id,name,status
# Dry run — show the request without sending
lemonsqueezy-pp-cli affiliates list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
lemonsqueezy-pp-cli affiliates list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
lemonsqueezy-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/lemonsqueezy-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
LEMONSQUEEZY_API_KEY | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, lemonsqueezy-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
lemonsqueezy-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $LEMONSQUEEZY_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- doctor reports
LEMONSQUEEZY_API_KEY not set — Export LEMONSQUEEZY_API_KEY=<your-key> in your shell (or persist in ~/.zshenv for non-interactive subprocesses).
- 401 Unauthorized on any command — The API key is invalid or revoked. Generate a fresh one at app.lemonsqueezy.com/settings/api.
- 429 Too Many Requests — Lemon Squeezy rate-limits at 300 req/min per IP. Rerun after the
Retry-After window or narrow sync --resources to a smaller set.
- churn-watch/mrr-trend return empty rows — Run
sync --resources subscriptions,subscription-invoices --full first — these commands read the local mirror, not the live API.
- campaign-watch projects nonsense sellout times — The projection needs at least 6 hours of redemption history. Resync
discount-redemptions and rerun once redemptions exist in the window.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press