pp-stripe

# 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.5 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 alice@example.com --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-pp-cli accounts post-account` — <p>Updates a <a href='/connect/accounts'>connected account</a> by setting the values of the parameters passed. Any... **apple-pay** — Manage apple pay - `stripe-pp-cli apple-pay delete-domains-domain` — <p>Delete an apple pay domain.</p> - `stripe-pp-cli apple-pay get-domains` — <p>List apple pay domains.</p> - `stripe-pp-cli apple-pay get-domains-domain` — <p>Retrieve an apple pay domain.</p> - `stripe-pp-cli apple-pay post-domains` — <p>Create an apple pay domain.</p> **application-fees** — Manage application fees - `stripe-pp-cli application-fees get` — <p>Returns a list of application fees you’ve previously collected. The application fees are returned in sorted... - `stripe-pp-cli application-fees get-id` — <p>Retrieves the details of an application fee that your account has collected. The same information is returned... **apps** — Manage apps - `stripe-pp-cli apps get-secrets` — <p>List all secrets stored on the given scope.</p> - `stripe-pp-cli apps get-secrets-find` — <p>Finds a secret in the secret store by name and scope.</p> - `stripe-pp-cli apps post-secrets` — <p>Create or replace a secret in the secret store.</p> - `stripe-pp-cli apps post-secrets-delete` — <p>Deletes a secret from the secret store by name and scope.</p> **balance** — Manage balance - `stripe-pp-cli balance` — <p>Retrieves the current account balance, based on the authentication that was used to make the request. For a... **balance-settings** — Manage balance settings - `stripe-pp-cli balance-settings get` — <p>Retrieves balance settings for a given connected account. Related guide: <a href='/connect/authentication'>Making... - `stripe-pp-cli balance-settings post` — <p>Updates balance settings for a given connected account. Related guide: <a href='/connect/authentication'>Making... **balance-transactions** — Manage balance transactions - `stripe-pp-cli balance-transactions get` — <p>Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges, transfers, and... - `stripe-pp-cli balance-transactions get-id` — <p>Retrieves the balance transaction with the given ID.</p> <p>Note that this endpoint previously used the path... **billing** — Manage billing - `stripe-pp-cli billing get-alerts` — <p>Lists billing active and inactive alerts</p> - `stripe-pp-cli billing get-alerts-id` — <p>Retrieves a billing alert given an ID</p> - `stripe-pp-cli billing get-credit-balance-summary` — <p>Retrieves the credit balance summary for a customer.</p> - `stripe-pp-cli billing get-credit-balance-transactions` — <p>Retrieve a list of credit balance transactions.</p> - `stripe-pp-cli billing get-credit-balance-transactions-id` — <p>Retrieves a credit balance transaction.</p> - `stripe-pp-cli billing get-credit-grants` — <p>Retrieve a list of credit grants.</p> - `stripe-pp-cli billing get-credit-grants-id` — <p>Retrieves a credit grant.</p> - `stripe-pp-cli billing get-meters` — <p>Retrieve a list of billing meters.</p> - `stripe-pp-cli billing get-meters-id` — <p>Retrieves a billing meter given an ID.</p> - `stripe-pp-cli billing get-meters-id-event-summaries` — <p>Retrieve a list of billing meter event summaries.</p> - `stripe-pp-cli billing post-alerts` — <p>Creates a billing alert</p> - `stripe-pp-cli billing post-alerts-id-activate` — <p>Reactivates this alert, allowing it to trigger again.</p> - `stripe-pp-cli billing post-alerts-id-archive` — <p>Archives this alert, removing it from the list view and APIs. This is non-reversible.</p> - `stripe-pp-cli billing post-alerts-id-deactivate` — <p>Deactivates this alert, preventing it from triggering.</p> - `stripe-pp-cli billing post-credit-grants` — <p>Creates a credit grant.</p> - `stripe-pp-cli billing post-credit-grants-id` — <p>Updates a credit grant.</p> - `stripe-pp-cli billing post-credit-grants-id-expire` — <p>Expires a credit grant.</p> - `stripe-pp-cli billing post-credit-grants-id-void` — <p>Voids a credit grant.</p> - `stripe-pp-cli billing post-meter-event-adjustments` — <p>Creates a billing meter event adjustment.</p> - `stripe-pp-cli billing post-meter-events` — <p>Creates a billing meter event.</p> - `stripe-pp-cli billing post-meters` — <p>Creates a billing meter.</p> - `stripe-pp-cli billing post-meters-id` — <p>Updates a billing meter.</p> - `stripe-pp-cli billing post-meters-id-deactivate` — <p>When a meter is deactivated, no more meter events will be accepted for this meter. You can’t attach a... - `stripe-pp-cli billing post-meters-id-reactivate` — <p>When a meter is reactivated, events for this meter can be accepted and you can attach the meter to a price.</p> **billing-portal** — Manage billing portal - `stripe-pp-cli billing-portal get-configurations` — <p>Returns a list of configurations that describe the functionality of the customer portal.</p> - `stripe-pp-cli billing-portal get-configurations-configuration` — <p>Retrieves a configuration that describes the functionality of the customer portal.</p> - `stripe-pp-cli billing-portal post-configurations` — <p>Creates a configuration that describes the functionality and behavior of a PortalSession</p> - `stripe-pp-cli billing-portal post-configurations-configuration` — <p>Updates a configuration that describes the functionality of the customer portal.</p> - `stripe-pp-cli billing-portal post-sessions` — <p>Creates a session of the customer portal.</p> **charges** — Manage charges - `stripe-pp-cli charges get` — <p>Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most... - `stripe-pp-cli charges get-charge` — <p>Retrieves the details of a charge that has previously been created. Supply the unique charge ID that was returned... - `stripe-pp-cli charges get-search` — <p>Search for charges you’ve previously created using Stripe’s <a... - `stripe-pp-cli charges post` — <p>This method is no longer recommended—use the <a href='/docs/api/payment_intents'>Payment Intents API</a> to... - `stripe-pp-cli charges post-charge` — <p>Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be... **checkout** — Manage checkout - `stripe-pp-cli checkout get-sessions` — <p>Returns a list of Checkout Sessions.</p> - `stripe-pp-cli checkout get-sessions-session` — <p>Retrieves a Checkout Session object.</p> - `stripe-pp-cli checkout get-sessions-session-line-items` — <p>When retrieving a Checkout Session, there is an includable <strong>line_items</strong> property containing the... - `stripe-pp-cli checkout post-sessions` — <p>Creates a Checkout Session object.</p> - `stripe-pp-cli checkout post-sessions-session` — <p>Updates a Checkout Session object.</p> <p>Related guide: <a href='/payments/advanced/dynamic-updates'>Dynamically... - `stripe-pp-cli checkout post-sessions-session-expire` — <p>A Checkout Session can be expired when it is in one of these statuses: <code>open</code> </p> <p>After it... **climate** — Manage climate - `stripe-pp-cli climate get-orders` — <p>Lists all Climate order objects. The orders are returned sorted by creation date, with the most recently created... - `stripe-pp-cli climate get-orders-order` — <p>Retrieves the details of a Climate order object with the given ID.</p> - `stripe-pp-cli climate get-products` — <p>Lists all available Climate product objects.</p> - `stripe-pp-cli climate get-products-product` — <p>Retrieves the details of a Climate product with the given ID.</p> - `stripe-pp-cli climate get-suppliers` — <p>Lists all available Climate supplier objects.</p> - `stripe-pp-cli climate get-suppliers-supplier` — <p>Retrieves a Climate supplier object.</p>