Lemon Squeezy CLI
lmsq is a CLI for the Lemon Squeezy API with 62 operations across 22 resource types.
When to use this skill
Use this when the user asks you to:
- Query or manage Lemon Squeezy resources (orders, subscriptions, customers, products, etc.)
- Check subscription statuses, order details, or license key states
- Create checkouts, discounts, or webhooks
- Activate, validate, or deactivate license keys
- Refund orders or subscription invoices
- Generate invoices
Prerequisites
Install the CLI if not already available:
npm install -g lmsq
Or run without installing: npx lmsq <command>
Authentication
Set the API key via environment variable (preferred for agents):
export LEMONSQUEEZY_API_KEY=lsq_live_xxxxxxxxxxxx
Or authenticate persistently:
lmsq auth login --key lsq_live_xxxxxxxxxxxx
Resolution order: --api-key flag > LEMONSQUEEZY_API_KEY env var > ~/.config/lemonsqueezy-cli/config.json
Exception: lmsq licenses activate/validate/deactivate uses the public License API and requires no authentication.
Output for agents
When called from a non-TTY shell (which is how agents call it), output is automatically token-efficient flat key: value text with no colors or decoration.
Always minimize token usage by choosing the right output mode:
| Mode | Use when | Tokens |
|---|---|---|
--pluck <field> | You need a single value from a single resource | ~1 |
--count | You need the total number of matching resources | ~3 |
--only-ids | You need a list of IDs | ~5 per resource |
--fields a,b,c | You need a few specific attributes | ~20 per resource |
| (default) | You need all attributes | ~150 per resource |
--json | You need structured data for parsing | ~200 per resource |
Do not use --json-raw unless the user specifically asks for the raw JSON:API response. It costs ~2,000 tokens per resource.
Command patterns
All resources follow consistent patterns:
lmsq <resource> list [--store-id <id>] [--filters] [-p <page>] [-s <size>]
lmsq <resource> get <id>
lmsq <resource> create [--required-options] [--optional-options]
lmsq <resource> update <id> [--options]
lmsq <resource> delete <id>
Common flags on every command
| Flag | Effect |
|---|---|
--json | Flattened JSON output |
-f, --fields a,b | Return only specific attributes |
--api-key <key> | Override the stored API key |
--color / --no-color | Force or disable color |
List command flags
| Flag | Effect |
|---|---|
-p, --page <n> | Page number (default: 1) |
-s, --page-size <n> | Results per page (default: 5, max: 100) |
--only-ids | One ID per line |
--count | Just the total count |
--first | Return only the first result |
Get command flags
| Flag | Effect |
|---|---|
--pluck <field> | Return just the bare value of one field |
Examples
# Check how many active subscriptions exist
lmsq subscriptions list --status active --count
# Get a customer's email
lmsq customers get 456 --pluck email
# List recent orders with key fields
lmsq orders list --page-size 10 --fields status,total,user_email
# Get all active subscription IDs
lmsq subscriptions list --status active --only-ids --page-size 100
# Check a subscription's status
lmsq subscriptions get 789 --pluck status
# Create a checkout link
lmsq checkouts create --store-id 1 --variant-id 1
# Refund an order
lmsq orders refund 12345
# Pause a subscription
lmsq subscriptions update 789 --pause void
# Resume a paused subscription
lmsq subscriptions update 789 --unpause
# Activate a license key (no auth needed)
lmsq licenses activate --key XXXXX-XXXXX-XXXXX --instance-name "server-1"
# Validate a license key (no auth needed)
lmsq licenses validate --key XXXXX-XXXXX-XXXXX
Available resources
See references/COMMANDS.md for the full command reference with all resources, subcommands, and their options.
Quick overview:
| Resource | Actions |
|---|---|
auth | login, logout, status |
user | (show current user) |
stores | list, get |
customers | list, get, create, update, archive |
products | list, get |
variants | list, get |
prices | list, get |
files | list, get |
orders | list, get, invoice, refund |
order-items | list, get |
subscriptions | list, get, update, cancel |
subscription-invoices | list, get, generate, refund |
subscription-items | list, get, update, usage |
usage-records | list, get, create |
discounts | list, get, create, delete |
discount-redemptions | list, get |
license-keys | list, get, update |
license-key-instances | list, get |
checkouts | list, get, create |
webhooks | list, get, create, update, delete |
affiliates | list, get |
licenses | activate, validate, deactivate |
Lemon Squeezy documentation
If you need to understand platform behavior beyond what the CLI covers:
- Help docs — how Lemon Squeezy works (billing, subscriptions, license keys, etc.)
- API reference — full API documentation with field descriptions and response schemas
- Guides — tutorials and integration walkthroughs
Tips
- Use
lmsq <command> --helpto see all options for any command. - Most list commands support
--store-idto filter by store. - List commands support
--include <resources>for related data (e.g.--include customer,order-items). - For subscriptions:
--cancelled(via update) cancels at end of billing period;cancelcancels immediately. - Pause modes:
--pause void(loses access) vs--pause free(keeps access). - License key special values:
--activation-limit unlimited,--expires-at never. - Discount amount types:
--amount-type percent(e.g. 20 = 20% off) vs--amount-type fixed(e.g. 500 = $5.00 off).