pp-lemonsqueezy

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/payments/lemonsqueezy/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Lemon Squeezy — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `lemonsqueezy-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install lemonsqueezy --cli-only
   ```
2. Verify: `lemonsqueezy-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/payments/lemonsqueezy/cmd/lemonsqueezy-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when running ongoing Lemon Squeezy operations — Monday-morning revenue/churn sweeps, post-refund license-key disables, live capacity tracking during a capped sale, or webhook coverage audits across multiple stores. The cross-entity SQL and transcendence commands are the differentiator. For one-shot dashboard tasks (creating one product, editing a single discount) the LS web UI is still faster.

## Anti-triggers

Do not use this CLI for:
- Building a custom checkout form in a web app — use the official `lemonsqueezy.js` JavaScript SDK (the CLI is for ops, not embedded billing).
- Receiving webhook payloads in production — this CLI can replay and audit webhooks, but the actual HTTP server lives in your application.
- Tax/VAT reporting — Lemon Squeezy is merchant-of-record and ships its own tax docs in the dashboard; this CLI doesn't replicate them.
- Customer-facing license validation in your desktop app — call the LS license API directly from the app, not via this CLI.

## Unique Capabilities

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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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'._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  lemonsqueezy-pp-cli webhook-audit --json
  ```

## Command Reference

**affiliates** — Manage affiliates

- `lemonsqueezy-pp-cli affiliates get` — Lemon Squeezy Retrieve an affiliate
- `lemonsqueezy-pp-cli affiliates list` — Lemon Squeezy List all affiliates

**checkouts** — Manage checkouts

- `lemonsqueezy-pp-cli checkouts create` — Lemon Squeezy Create a checkout
- `lemonsqueezy-pp-cli checkouts get` — Lemon Squeezy Retrieve a checkout
- `lemonsqueezy-pp-cli checkouts list` — Lemon Squeezy List all checkouts

**customers** — Manage customers

- `lemonsqueezy-pp-cli customers get` — Lemon Squeezy Retrieve a customer
- `lemonsqueezy-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 redemption
- `lemonsqueezy-pp-cli discount-redemptions list` — Lemon Squeezy List all discount redemptions

**discounts** — Manage discounts

- `lemonsqueezy-pp-cli discounts create` — Lemon Squeezy Create a discount
- `lemonsqueezy-pp-cli discounts delete` — Lemon Squeezy Delete a discount
- `lemonsqueezy-pp-cli discounts get` — Lemon Squeezy Retrieve a discount
- `lemonsqueezy-pp-cli discounts list` — Lemon Squeezy List all discounts

**files** — Manage files

- `lemonsqueezy-pp-cli files get` — Lemon Squeezy Retrieve a file
- `lemonsqueezy-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 instance
- `lemonsqueezy-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 key
- `lemonsqueezy-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 item
- `lemonsqueezy-pp-cli order-items list` — Lemon Squeezy List all order items

**orders** — Manage orders

- `lemonsqueezy-pp-cli orders get` — Lemon Squeezy Retrieve an order
- `lemonsqueezy-pp-cli orders list` — Lemon Squeezy List all orders

**prices** — Manage prices

- `lemonsqueezy-pp-cli prices get` — Lemon Squeezy Retrieve a price
- `lemonsqueezy-pp-cli prices list` — Lemon Squeezy List all prices