pp-stripe

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/payments/stripe/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/". -->

# Stripe — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `stripe-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 stripe --cli-only
   ```
2. Verify: `stripe-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/stripe/cmd/stripe-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 stripe-pp-cli when you need to (1) run analytics across customers/subs/invoices that Stripe's dashboard doesn't expose, (2) script payment ops in a CI/agent loop without daemon processes, (3) reconcile payouts and balance transactions, or (4) feed Stripe state into a non-Stripe system (CRM, accounting, outreach automation).

## When NOT to Use This CLI (anti-triggers)

Do not use stripe-pp-cli for:

- **Live-mode bulk writes you have not audited.** Mutating commands (POST/PUT/PATCH/DELETE) against an `sk_live_...` key are blocked by default with a clear error; pass `--confirm-live` (or set `STRIPE_CONFIRM_LIVE=1`) once you have audited the invocation. Prefer `sk_test_...` for development regardless.
- **In-person Terminal payments.** `terminal` resource commands are present but Stripe Terminal SDK is not in scope. Use the Terminal iOS/Android SDK.
- **Stripe Issuing card management workflows.** `issuing` commands are REST passthrough only; spending controls, dispute evidence packages not built. Use the Stripe Dashboard.
- **Stripe Tax registration.** `tax-rates` CRUD only; jurisdiction registration not in scope. Use Stripe Tax in Dashboard.
- **Connect platform fan-out across many connected accounts.** Single account at a time via `Stripe-Account` header. Multi-account loops via external script.
- **Local mock-server testing.** Use [stripe-mock](https://github.com/stripe/stripe-mock) directly via `STRIPE_BASE_URL=http://localhost:12111`.

## Not Yet Wired (deferred to v0.2)

| Area | Status | Workaround |
|------|--------|-----------|
| Stripe Issuing (full workflow) | endpoint passthrough only | Use Stripe Dashboard |
| Stripe Terminal (in-person SDK) | endpoint passthrough only | Use Terminal SDK |
| Stripe Tax registration | `tax-rates` CRUD only | Use Stripe Tax in Dashboard |
| `localstripe` mock server | out of scope | Use `stripe-mock` via `STRIPE_BASE_URL` |
| Connect account fan-out | single-account at a time | External script loops |

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`health`** — Compute a 0-100 health score for one or many customers from local SQLite, factoring in failed-payment count, dispute history, MRR contribution, subscription status, and account age.

  _Use this to feed customer-health signals into outreach, dunning, and renewal automation without burning hundreds of API calls per customer._

  ```bash
  stripe-pp-cli health cus_xyz --json --select score,failed_payments,mrr_contribution
  ```
- **`dunning-queue`** — List invoices in past_due/uncollectible state ranked by days-overdue, with last failure reason and customer email pulled from the local store.

  _When deciding which customers to follow up with about failed payments, this beats walking the Stripe dashboard or chaining 4+ API calls per row._

  ```bash
  stripe-pp-cli dunning-queue --json --select invoice,customer_email,days_overdue,last_failure_reason
  ```
- **`sql`** — Run read-only SQLite queries against the local Stripe mirror. All synced data lives in a generic 'resources' table — query with json_extract(data, '$.field') and filter by resource_type.

  _When a one-off question doesn't fit the canned commands, drop into SQL instead of writing a script that hits the API a thousand times._

  ```bash
  stripe-pp-cli sql "SELECT json_extract(data,'$.email') AS email, COUNT(*) AS active_subs FROM resources WHERE resource_type='subscriptions' AND json_extract(data,'$.status')='active' GROUP BY json_extract(data,'$.customer') HAVING active_subs > 1" --json
  ```
- **`payout-reconcile`** — Join payouts to balance_transactions to charges to customers from local store; flag missing balance_transactions and mismatches; CSV export.

  _Use this for end-of-period payout reconciliation against bank statements or accounting systems — replaces the manual CSV-pivot ritual._

  ```bash
  stripe-pp-cli payout-reconcile --since 7d --csv
  ```
- **`subs-at-risk`** — List subscriptions whose default payment method's card expires in a window, sorted by current MRR contribution.

  _Use this monthly to proactively email customers whose card is about to expire — prevents involuntary churn._

  ```bash
  stripe-pp-cli subs-at-risk --within 30d --json --select customer_email,mrr,card_exp
  ```
- **`metadata-grep`** — Search every synced resource's metadata bag for a key/value across resource types; returns (resource_type, id, matched_kv) rows.

  _When integrating Stripe with a CRM via metadata tags, this finds every related resource in one query._

  ```bash
  stripe-pp-cli metadata-grep 'crm_id=acme-001' --json
  ```

### Agent-native plumbing
- **`customer-360`** — One-shot dossier: customer profile + active subs + recent invoices + payment methods + recent charges + open disputes + lifetime spend.

  _Use this as the first command when investigating a customer ticket, support escalation, or churn risk — full context in one call._

  ```bash
  stripe-pp-cli customer-360 [email protected] --json --compact
  ```
- **`events-since`** — Fetch all Events since a cursor, persist new cursor in profile, no daemon. One-shot replacement for stripe-cli's listen daemon.

  _Use this in cron-driven agent loops to replay only new events since the last run — no daemon to babysit, no missed events._

  ```bash
  stripe-pp-cli events-since --type 'invoice.*' --json --select id,type,created,data.object.id
  ```

## Command Reference

**account** — Manage account

- `stripe-pp-cli account` — <p>Retrieves the details of an account.</p>

**account-links** — Manage account links

- `stripe-pp-cli account-links` — <p>Creates an AccountLink object that includes a single-use Stripe URL that the platform can redirect their user to...

**account-sessions** — Manage account sessions

- `stripe-pp-cli account-sessions` — <p>Creates a AccountSession object that includes a single-use token that the platform can use on their front-end to...

**accounts** — Manage accounts

- `stripe-pp-cli accounts delete` — <p>With <a href='/connect'>Connect</a>, you can delete accounts you manage.</p> <p>Test-mode accounts can be deleted...
- `stripe-pp-cli accounts get` — <p>Returns a list of accounts connected to your platform via <a href='/docs/connect'>Connect</a>. If you’re not a...
- `stripe-pp-cli accounts get-account` — <p>Retrieves the details of an account.</p>
- `stripe-pp-cli accounts post` — <p>With <a href='/docs/connect'>Connect</a>, you can create Stripe accounts for your users. To do this, you’ll...
- `stripe-