lemonsqueezy

name	lemonsqueezy
description	Manage a Lemon Squeezy store from the command line. Use when the user needs to query or manage orders, subscriptions, customers, license keys, checkouts, discounts, webhooks, or any other Lemon Squeezy resource. Provides token-efficient output optimized for AI agents.

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> --help to see all options for any command.
• Most list commands support --store-id to 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; cancel cancels 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).