I Built a CLI That Turns RevenueCat's Charts API Into a Subscription Health Dashboard

The Problem with Subscription Dashboards

Every subscription app founder I've talked to has the same relationship with their metrics dashboard: they open it reactively, usually after something already went wrong. MRR is down. Churn spiked. Trials converted at half the usual rate. The dashboard shows them what happened. It rarely tells them what to do.

RevenueCat's new Charts API changes the equation. For the first time, the subscription intelligence that previously lived behind a web UI is now available programmatically — meaning you can pull it into scripts, CI pipelines, scheduled reports, Slack bots, or anything else you build. The data is no longer locked in a dashboard you only open when you're worried.

I wanted to build something that demonstrates what's actually possible when subscription data is treated as a first-class API resource. The result is revenuecat-pulse: a Python CLI and library that fetches your key metrics, renders them as a terminal dashboard with trend sparklines, and uses Claude AI to generate a plain-English strategic analysis.

What I Built

revenuecat-pulse is a single pip-installable tool that does three things:

1. Fetches multiple Charts API endpoints in parallel — MRR, ARR, revenue, actives, churn, new customers, trials, and more
2. Renders a terminal dashboard with summary cards (including ASCII sparklines showing 12-month trends) and optional full time-series tables
3. Analyzes the numbers using Claude AI to produce a sharp, bulleted strategic read on your subscription health

The terminal output looks like this:

╭─────────────────────────────────╮
│ RevenueCat Pulse  •  Dark Noise │
│ 2024-01-01 → 2024-12-31         │
╰─────────────────────────────────╯

╭──────── MRR ─────────╮ ╭──────── ARR ─────────╮ ╭────── Revenue ───────╮
│ $4.7K                │ │ $55.9K               │ │ $4.8K                │
│ ▲ 1.0%               │ │ ▲ 1.0%               │ │ ▼ 26.2%              │
│ ▁▃▅▅▆▆▇█▅▄▅▅         │ │ ▁▃▅▅▆▆▇█▅▄▅▅         │ │ ▄▂▃▄▂▂▁▁▇█▅▂         │
╰──────────────────────╯ ╰──────────────────────╯ ╰──────────────────────╯
╭────── Actives ───────╮ ╭───── Churn Rate ─────╮ ╭─── New Customers ────╮
│ 2,640                │ │ 4.9%                 │ │ 3,076                │
│ ▲ 1.8%               │ │ ▼ 41.0%              │ │ ▲ 10.0%              │
│ ▁▃▅▅▆▆▇█▅▄▄▅         │ │ ▁▁▁▄▂▂▂▁█▇▄▂         │ │ ▆█▅▃▃▂▁▁▇▅▁▁         │
╰──────────────────────╯ ╰──────────────────────╯ ╰──────────────────────╯

You can also export a self-contained HTML report — dark-mode, no external dependencies — to share with co-founders or investors.

Architecture

The library has four modules, each with a single responsibility:

RevenueCat Charts API
        │
        ▼
  RevenueCatClient              ← httpx, handles auth + rate limiting
  (client.py)
        │
        ▼
  ChartData / DataPoint models  ← typed dataclasses
  (client.py)
        │
   ┌────┴─────┐
   ▼          ▼
Reporter   InsightsEngine
(reporter.py)  (insights.py)
   │          │
   ▼          ▼
 Rich       Anthropic
 terminal   Claude API
 + HTML

RevenueCatClient wraps the Charts API v2. It handles Bearer auth, respects the 15 req/min rate limit with a small sleep between requests, and parses the flat values array into typed Python dataclasses.

The ChartData model is where most of the useful work happens. The raw API returns values as a flat array where each period's multiple measures are interleaved — separate objects sharing the same cohort timestamp. ChartData normalizes this into a time_series(measure_index) method that returns clean (datetime, float) pairs, plus convenience methods like latest_value() and period_change_pct().

Reporter uses Rich to render terminal output and generates standalone HTML with no external CSS dependencies — so you can email it directly or host it as a static file.

InsightsEngine builds a compact text summary of the current metrics and sends it to Claude with a system prompt instructing it to act as a subscription business analyst. The output is deliberately constrained to 3-5 actionable bullets.

Real Data: What I Found in Dark Noise's 2024 Metrics

RevenueCat provided me with read-only access to Dark Noise — a popular white noise app for iOS. I ran revenuecat-pulse against it for the full year 2024 and the data tells a clear story.

The churn table immediately surfaced something important:

 Period         Actives   Churned Actives   Churn Rate
───────────────────────────────────────────────────────
 Jan 2024         2,130                48         2.2%
 Feb 2024         2,328                50         2.1%
 Mar 2024         2,516                44         1.8%
 Apr 2024         2,701               228         8.4%  ← first spike
 May 2024         2,664               134         5.0%
 Jun 2024         2,711               124         4.6%
 Jul 2024         2,769               117         4.2%
 Aug 2024         2,805                84         3.0%
 Sep 2024         2,861               407        14.2%  ← major spike
 Oct 2024         2,682               334        12.4%  ← extended
 Nov 2024         2,618               219         8.4%
 Dec 2024         2,593               128         4.9%

Two churn spikes stand out. The first, in April (8.4%), and the larger cluster in September–October (14.2% and 12.4%). MRR stayed relatively stable throughout — rising from $4.1K in January to $5.0K peak in August before settling at $4.7K in December — because new subscriber acquisition was continuously offsetting churn.

The September spike almost certainly reflects annual subscription cohorts from the previous fall App Store season expiring simultaneously. This is a known pattern for indie apps with iOS seasonality: a surge of new subscribers in September (back-to-school) who all have the same renewal date one year later. The MRR chart tells you the business is healthy. The churn chart tells you there's a concentrated renewal risk every September that the founder should plan for.

Without a tool like this, you'd need to manually cross-reference the RevenueCat dashboard and build these observations yourself. The pulse CLI makes it a single command.

The Code

Install with pip:

pip install revenuecat-pulse

# With AI insights
pip install "revenuecat-pulse[ai]"

Run your first report:

pulse report \
  --api-key sk_your_key \
  --project-id proj_your_id \
  --export report.html

Or use it as a Python library:

from revenuecat_pulse import RevenueCatClient, generate_insights

with RevenueCatClient("sk_your_key") as client:
    charts = client.get_charts(
        project_id="proj_your_id",
        chart_names=["mrr", "churn", "actives"],
        start_date="2024-01-01",
        end_date="2024-12-31",
    )

mrr = charts["mrr"]
print(f"Current MRR: {mrr.latest_value()}")   # 4658.17
print(f"MoM change: {mrr.period_change_pct():.1f}%")  # +1.0%

# Get a full time series
for date, value in mrr.time_series():
    print(f"{date.strftime('%b %Y')}: ${value:.0f}")

# AI-powered strategic analysis
insights = generate_insights(charts, anthropic_api_key="sk-ant-...")
print(insights)

The library is intentionally minimal — three core methods on ChartData cover 90% of use cases. The CLI wraps them with sensible defaults so you get value immediately without reading the docs.

Why an AI Layer Matters Here

The subscription metrics themselves are not hard to fetch or display. The hard part is interpretation. A 14% churn rate in September might be:

• A normal seasonal cohort expiration (not alarming)
• A sign that a competitor launched a competing app (alarming)
• The result of an App Store price increase (controllable)
• Billing failure from a payment processor change (fixable)

The AI insights layer feeds a compact summary of the current numbers to Claude with a directive to "give me a sharp strategic read." It won't tell you which of the four scenarios applies — only you know your context — but it forces the key questions to the surface in seconds instead of minutes of staring at charts.

This is the pattern I think will define the next generation of developer tools: raw API access + AI interpretation layer + clean CLI interface. The data is there. The interpretation used to require a human analyst. Now it requires a single flag.

What's Next

The current version is a solid v0.1. Things I want to add:

• Slack/Discord webhook integration — post a daily pulse to your team channel
• Anomaly detection — alert when churn rate exceeds 2x the 30-day average
• Segment support — the Charts API supports segmentation by country, product, store, etc.
• GitHub Actions integration — a YAML workflow template for weekly scheduled reports
• MRR movement chart — decompose MRR change into new, expansion, contraction, and churn

If you use RevenueCat and any of these would be useful to you, open an issue or PR on GitHub. I'm building this in the open.