revcat

name

revcat

description

RevenueCat CLI tool for subscription analytics, MRR tracking, customer management, and offering configuration. Use when analyzing app revenue, checking subscriber status, managing offerings/packages/entitlements, querying chart data, setting up webhooks, or any RevenueCat API interaction via CLI. Triggers on "revcat", "RevenueCat", "MRR", "subscription analytics", "revenue metrics", "offerings", "entitlements", "paywalls", or when the user wants to interact with RevenueCat data.

revcat CLI

CLI wrapping RevenueCat API v2. All output is JSON. Requires REVENUECAT_API_KEY env var (v2 secret key from RevenueCat Dashboard > Project Settings > API Keys).

Install: bun install -g @metehankurucu/revcat

Setup

export REVENUECAT_API_KEY=sk_your_key
export REVENUECAT_PROJECT_ID=proj_your_id  # optional default

Find project ID: revcat projects list

Command Pattern

revcat <resource> <action> --project <id> [options]

All commands require --project (or REVENUECAT_PROJECT_ID env var) except projects list.

Global options: --api-key <key>, --compact (single-line JSON; default pretty).

Pagination: any list/search command that takes --limit also takes --starting-after <cursor> and --all. --all auto-follows every page (capped at 20, stderr warning if truncated) and returns one merged items array with pages_fetched and truncated.

Core Workflows

Revenue Analysis

# Overview: MRR, revenue, active subs, trials, new customers
revcat charts overview --project proj123

# MRR trend (monthly)
revcat charts data --project proj123 --chart mrr --start 2025-01-01 --end 2025-12-31 --resolution month

# Churn rate (weekly)
revcat charts data --project proj123 --chart churn --start 2026-01-01 --end 2026-02-21 --resolution week

# Chart names (validated against the RevenueCat v2 spec; an unknown --chart is
# rejected before any request with a JSON did_you_mean suggestion):
#   actives, actives_movement, actives_new, arr, churn, cohort_explorer,
#   conversion_to_paying, customers_new, initial_conversion, ltv_per_customer,
#   ltv_per_paying_customer, mrr, mrr_movement, prediction_explorer, refund_rate,
#   revenue, subscription_retention, subscription_status, trials, trials_movement,
#   trials_new, customers_active, trial_conversion_rate, non-subscription_purchases
# Pass --unsafe-chart to skip validation and send the value as-is.

# Discover chart options (resolutions, segments, filters)
revcat charts options --project proj123 --chart revenue

Customer Investigation

revcat customers get --project proj123 --customer cust_abc
revcat customers entitlements --project proj123 --customer cust_abc
revcat customers subscriptions --project proj123 --customer cust_abc
revcat customers purchases --project proj123 --customer cust_abc
revcat customers attributes --project proj123 --customer cust_abc

# Tag for segmentation
revcat customers set-attributes --project proj123 --customer cust_abc \
  --data '{"segment": {"value": "power_user"}}'

# A/B test: assign specific offering
revcat customers assign-offering --project proj123 --customer cust_abc --offering ofrng_xyz

Offering Management

revcat offerings list --project proj123
revcat offerings create --project proj123 --lookup-key premium-v2 --display-name "Premium V2"
revcat offerings update --project proj123 --offering ofrng_abc --display-name "Updated Name" --is-current

# Packages within offerings
revcat packages create --project proj123 --offering ofrng_abc --lookup-key monthly --display-name "Monthly"
revcat packages attach-products --project proj123 --package pkg_abc --products '[{"product_id":"prod_xyz"}]'
revcat packages detach-products --project proj123 --package pkg_abc --product-ids prod_xyz

Entitlement Management

revcat entitlements list --project proj123
revcat entitlements create --project proj123 --lookup-key premium --display-name "Premium Access"
revcat entitlements attach-products --project proj123 --entitlement entl_abc --product-ids prod_1,prod_2

Subscription Lookup

revcat subscriptions search --project proj123 --store-identifier "450001234567890"
revcat subscriptions get --project proj123 --subscription sub_abc
revcat subscriptions entitlements --project proj123 --subscription sub_abc
revcat subscriptions transactions --project proj123 --subscription sub_abc

Webhook Setup

revcat webhooks create --project proj123 --url "https://api.myapp.com/webhook" --name "Prod" --environment production
revcat webhooks update --project proj123 --webhook wh_abc --url "https://new-url.com/hook"

Available Resources

Resource	Actions	Notes
projects	list
apps	list, get, keys
charts	overview, data, options	5 req/min rate limit
customers	list, get, entitlements, aliases, attributes, set-attributes, purchases, subscriptions, vc-balances, assign-offering
entitlements	list, get, products, create, update, attach-products, detach-products
offerings	list, get, create, update
packages	list, get, products, create, update, attach-products, detach-products
products	list, get	read-only
subscriptions	search, get, entitlements, transactions, management-url	read-only
purchases	search, get, entitlements	read-only
invoices	list, get	read-only
audit-logs	list	read-only
collaborators	list	read-only
virtual-currencies	list, get	read-only
webhooks	list, get, create, update
paywalls	list, get, create

For full command details with all options, see references/commands.md.

Rate Limits

Domain	Limit	Commands
charts_metrics	5/min	charts
customer_information	480/min	customers, subscriptions, purchases
project_configuration	60/min	everything else

A per-domain token bucket paces requests proactively. If the API still returns 429 (or a retryable 5xx), the client retries automatically up to 2 times, waiting the body's backoff_ms, then Retry-After, then a capped exponential backoff; each retry is announced on stderr as a JSON line. After exhaustion the final error is the standard JSON envelope with retryable: true.

Safety

Strict allowlist — only permitted operations execute. Blocked: all DELETE, refunds, grant/revoke entitlements, customer deletion/transfer, subscription cancellation, app/project creation/deletion, product store creation, virtual currency transactions.

API Specification

The full RevenueCat API v2 OpenAPI spec is kept as a single canonical copy at the repository root (api-spec.yaml). See references/api-spec.md for the pointer and refresh instructions.