Documentation

RevenueCat CLI

revenuecat-pp-cli

Install

$ npx -y @mvanhorn/printing-press-library install revenuecat

Installs the CLI binary and the agent skill for Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more. Add --cli-only or --skill-only for one half. Requires Node.

Documentation

Every RevenueCat v2 endpoint, plus a local database, offline search, and revenue/churn/refund intelligence the dashboard charts can't compose.

Drive the full RevenueCat Developer API v2 from the shell or an agent: customers, subscriptions, entitlements, products, offerings, purchases, invoices, and charts. On top of the typed endpoint surface it adds a local SQLite mirror and novel commands — revenue-snapshot with run-over-run diffs, mrr-trend with movement decomposition, churn-watch with dollar exposure, dunning-alert, entitlement-rollup, refund-cascade, and trial-funnel — that join synced data in ways no single API call returns.

Created by @jcastillo725 (Joseph Alvin Castillo).

Authentication

RevenueCat v2 uses a server-side Secret API key sent as 'Authorization: Bearer '. Create one in the RevenueCat dashboard under Project Settings -> API Keys -> Secret API keys (a read-only key is enough for every read command). This is distinct from the public SDK keys. Set REVENUECAT_API_KEY and REVENUECAT_PROJECT_ID in your environment; run 'revenuecat-pp-cli doctor' to confirm both resolve against your project.

Quick Start

# Health check — confirms the binary and config wiring without calling the API.
revenuecat-pp-cli doctor --dry-run

# Pull the core entities into the local store so offline and join commands work.
revenuecat-pp-cli sync --resources customers,subscriptions,entitlements

# Current MRR/ARR/actives/revenue with deltas vs your last snapshot.
revenuecat-pp-cli revenue-snapshot --currency USD

# Who churned this week and the dollar exposure, as agent-native JSON.
revenuecat-pp-cli churn-watch --since 7d --agent

Unique Features

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

Revenue intelligence

revenue-snapshot — Point-in-time MRR, ARR, active subscriptions, trials, and revenue in your chosen currency, with deltas against your last snapshot.

Reach for this when an agent or operator asks 'where's revenue right now and how did it move since last check' in one call.
```
revenuecat-pp-cli revenue-snapshot --currency USD --agent
```
mrr-trend — MRR over time with new / expansion / contraction / churn movement decomposition and week-over-week deltas.

Reach for this to explain why MRR moved, not just that it moved.
```
revenuecat-pp-cli mrr-trend --period week --limit 12 --agent
```
trial-funnel — New trials to conversion-to-paying funnel with stage-to-stage drop-off.

Reach for this to see where trials leak before they convert.
```
revenuecat-pp-cli trial-funnel --since 30d --agent
```

Retention & risk

churn-watch — Which subscriptions flipped to billing-issue, grace, expired, or cancelled in a window, with per-subscription dollar exposure.

Reach for this when you need who churned and how much MRR they took, not just the churn rate line.
```
revenuecat-pp-cli churn-watch --since 7d --agent
```
dunning-alert — Subscriptions still in grace or billing-issue state joined with their unpaid invoices, ranked by recoverable amount.

Reach for this to act on failed billing while the revenue is still recoverable.
```
revenuecat-pp-cli dunning-alert --agent
```
entitlement-rollup — Per-entitlement active-customer counts and product attachments, flagging customers whose entitlement state disagrees with their subscription state.

Reach for this to catch silent entitlement desync (a dropped webhook, a refund that didn't cascade) across the whole customer base.
```
revenuecat-pp-cli entitlement-rollup --flag-disagreements --agent
```

Operations

refund-cascade — Traces a subscription or purchase through its transactions, refund history, and resulting entitlement loss; --apply issues the refund.

Reach for this to understand or execute a refund and see exactly which entitlements the customer loses.
```
revenuecat-pp-cli refund-cascade sub1a2b3c4d --agent
```
webhook-audit — Lists configured webhook integrations grouped by destination host, flagging duplicate or stale destinations.

Reach for this to confirm webhook delivery config before a dropped event silently desyncs entitlements.
```
revenuecat-pp-cli webhook-audit --agent
```

Recipes

Morning standup revenue line

revenuecat-pp-cli revenue-snapshot --currency USD --agent --select mrr,active_subscriptions,mrr_delta

One pasteable line of MRR, active subs, and the change since the last snapshot.

Recoverable failed billing

revenuecat-pp-cli dunning-alert --agent

Subscriptions still in grace or billing-issue joined with unpaid invoices, ranked by what you can still recover.

Find entitlement desync

revenuecat-pp-cli entitlement-rollup --flag-disagreements --agent

Surfaces customers whose entitlement state disagrees with their subscription state across the whole base.

Trace a refund's fallout

revenuecat-pp-cli refund-cascade sub1a2b3c4d --agent

Shows the transactions, refund history, and entitlements a customer loses before you issue the refund.

Usage

Run revenuecat-pp-cli --help for the full command reference and flag list.

Commands

apps

Operations about apps.

revenuecat-pp-cli apps create - This endpoint requires the following permission(s): project_configuration:apps:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli apps delete - This endpoint requires the following permission(s): project_configuration:apps:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli apps get - This endpoint requires the following permission(s): project_configuration:apps:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli apps list - This endpoint requires the following permission(s): project_configuration:apps:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli apps update - This endpoint requires the following permission(s): project_configuration:apps:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

audit-logs

Operations about audit logs.

revenuecat-pp-cli audit-logs <project_id> - This endpoint requires the following permission(s): project_configuration:audit_logs:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

charts

Manage charts

revenuecat-pp-cli charts <project_id> - Returns time-series data for a specific chart.

Response Structure

The response includes:

Chart metadata (category, display_name, description)
Time boundaries (start_date, end_date, last_computed_at)
Data values (array of data points)
Summary statistics
Segment information (when segmented)

Chart Types

Different charts may return data in slightly different formats:

Standard charts: values as arrays of data points with timestamps
Cohort charts: values include cohort-specific data structures
Segmented charts: include segment information in the response

Filtering and Segmentation

Use the /charts/{chart_name}/options endpoint to discover available filters and segments for a specific chart before making requests.

Filter parameters vary by chart and can be passed as additional query parameters.

Aggregation

Use aggregate to request summary-only output for supported charts. When aggregate is provided, values is returned as an empty array and summary includes only the requested aggregate operations.

Incomplete data For the most recent periods, data may be flagged as incomplete, and may not be appropriate to use for analysis. This endpoint requires the following permission(s): charts_metrics:charts:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 15 requests per minute.

collaborators

Operations about collaborators.

revenuecat-pp-cli collaborators <project_id> - This endpoint requires the following permission(s): project_configuration:collaborators:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

customers

Operations about customers.

revenuecat-pp-cli customers create - This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.
revenuecat-pp-cli customers delete - This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.
revenuecat-pp-cli customers get - This endpoint requires the following permission(s): customer_information:customers:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.
revenuecat-pp-cli customers list - This endpoint requires the following permission(s): customer_information:customers:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

entitlements

Operations about entitlements.

revenuecat-pp-cli entitlements create - This endpoint requires the following permission(s): project_configuration:entitlements:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli entitlements delete - This endpoint requires the following permission(s): project_configuration:entitlements:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli entitlements get - This endpoint requires the following permission(s): project_configuration:entitlements:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli entitlements list - This endpoint requires the following permission(s): project_configuration:entitlements:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli entitlements update - This endpoint requires the following permission(s): project_configuration:entitlements:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

integrations

Operations about integrations.

revenuecat-pp-cli integrations create-webhook - This endpoint requires the following permission(s): project_configuration:integrations:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli integrations delete-webhook - This endpoint requires the following permission(s): project_configuration:integrations:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli integrations get-webhook - This endpoint requires the following permission(s): project_configuration:integrations:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli integrations list-webhook - This endpoint requires the following permission(s): project_configuration:integrations:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli integrations update-webhook - This endpoint requires the following permission(s): project_configuration:integrations:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

media-assets

Manage media assets

revenuecat-pp-cli media-assets <project_id> - This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

metrics

Manage metrics

revenuecat-pp-cli metrics get-overview - This endpoint requires the following permission(s): charts_metrics:overview:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 15 requests per minute.
revenuecat-pp-cli metrics get-revenue - Returns the total revenue for the project across all of its apps for the given inclusive date range [start_date, end_date]. The value is expressed in the project's primary currency unless currency is provided.

This endpoint is backed by the same realtime (v3) revenue chart that powers the dashboard. It is intended for cases where an app needs an authoritative revenue total without inferring it from the transaction list.

Note that the most recent day in the range may be partial if it includes today, since transactions for today are still arriving. This endpoint requires the following permission(s): charts_metrics:overview:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 15 requests per minute.

offerings

Operations about offerings.

revenuecat-pp-cli offerings create - This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli offerings delete - This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli offerings get - This endpoint requires the following permission(s): project_configuration:offerings:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli offerings list - This endpoint requires the following permission(s): project_configuration:offerings:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli offerings update - This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

packages

Operations about packages.

revenuecat-pp-cli packages delete-from-offering - This endpoint requires the following permission(s): project_configuration:packages:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli packages get - This endpoint requires the following permission(s): project_configuration:packages:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli packages update - This endpoint requires the following permission(s): project_configuration:packages:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

paywalls

Operations about paywalls.

revenuecat-pp-cli paywalls create - Create a paywall draft for a project. You can either use the offering template shortcut or provide full draft components directly. This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli paywalls delete - This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli paywalls get - This endpoint requires the following permission(s): project_configuration:offerings:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli paywalls list - This endpoint requires the following permission(s): project_configuration:offerings:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli paywalls update - Update a paywall draft. If the paywall is already published, this updates its draft version without changing the published version. This endpoint requires the following permission(s): project_configuration:offerings:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

products

Operations about products.

revenuecat-pp-cli products create -

This endpoint requires the following permission(s): project_configuration:products:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

revenuecat-pp-cli products delete - This endpoint requires the following permission(s): project_configuration:products:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli products get - This endpoint requires the following permission(s): project_configuration:products:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli products list - This endpoint requires the following permission(s): project_configuration:products:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli products update - This endpoint requires the following permission(s): project_configuration:products:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

projects

Operations about projects.

revenuecat-pp-cli projects create - This endpoint requires the following permission(s): project_configuration:projects:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli projects list - This endpoint requires the following permission(s): project_configuration:projects:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

purchases

Operations about purchases.

revenuecat-pp-cli purchases get - This endpoint requires the following permission(s): customer_information:purchases:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.
revenuecat-pp-cli purchases search - Search for a one-time purchases by any of its associated store_purchase_identifier values.

For example, this may include the transactionId of any transaction in an Apple App Store purchase, or any order ID from a Google Play Store purchase. This endpoint requires the following permission(s): customer_information:purchases:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

subscriptions

Operations about subscriptions.

revenuecat-pp-cli subscriptions get - This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.
revenuecat-pp-cli subscriptions search - Search for a subscription by any of its associated store_subscription_identifier values, whether from a past or current subscription period.

For example, this may include the transactionId of any transaction in an Apple App Store subscription, or any order ID from a Google Play Store subscription. This endpoint requires the following permission(s): customer_information:subscriptions:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

virtual-currencies

Manage virtual currencies

revenuecat-pp-cli virtual-currencies create-virtual-currency - This endpoint requires the following permission(s): project_configuration:virtual_currencies:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli virtual-currencies delete-virtual-currency - This endpoint requires the following permission(s): project_configuration:virtual_currencies:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli virtual-currencies get-virtual-currency - This endpoint requires the following permission(s): project_configuration:virtual_currencies:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli virtual-currencies list - This endpoint requires the following permission(s): project_configuration:virtual_currencies:read. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.
revenuecat-pp-cli virtual-currencies update-virtual-currency - This endpoint requires the following permission(s): project_configuration:virtual_currencies:read_write. This endpoint belongs to the Project Configuration domain, which has a default rate limit of 60 requests per minute.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
revenuecat-pp-cli apps list mock-value

# JSON for scripting and agents
revenuecat-pp-cli apps list mock-value --json

# Filter to specific fields
revenuecat-pp-cli apps list mock-value --json --select id,name,status

# Dry run — show the request without sending
revenuecat-pp-cli apps list mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
revenuecat-pp-cli apps list mock-value --agent

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
Confirmable - --yes for explicit confirmation of destructive actions
Piped input - write commands can accept structured input when their help lists --stdin
Offline-friendly - sync/search commands can use the local SQLite store when available
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

revenuecat-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/developer-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
`REVENUECAT_API_KEY`	per_call	No	Set to your API credential.
`DEVELOPER_BEARER_AUTH`	per_call	No	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, revenuecat-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

Run revenuecat-pp-cli doctor to check credentials
Verify the environment variable is set: echo $REVENUECAT_API_KEY Not found errors (exit code 3)
Check the resource ID is correct
Run the list command to see available items

API-specific

doctor reports the API key is missing or invalid — Set REVENUECAT_API_KEY to a v2 Secret key (starts with sk_) from Project Settings -> API Keys; the public SDK keys will not work.
Commands return a project-not-found or 404 error — Set REVENUECAT_PROJECT_ID to your project id, or pass --project ; every v2 endpoint is project-scoped.
HTTP 429 rate-limit errors during sync or fan-out — RevenueCat rate-limits per domain; re-run sync with a smaller --resources set or let the built-in adaptive limiter back off.

For agents: pass /documentation/revenuecat/agents.md to install this CLI from a prompt.