gplay | Blog

AI-generated paywalls linked to real Google Play products: RevenueCat MCP + gplay

Sun, 05 Jul 2026 00:00:00 GMT

RevenueCat’s MCP server exposes an AI paywall generator — describe what you want, get a rendered paywall. Good, but a paywall pointing at products that don’t exist isn’t a paywall, it’s a mockup. To ship, the paywall needs to be linked to a real Google Play subscription with real base plans, real offers, and real prices.

That’s where gplay fits: it creates the actual Play-side objects, RC MCP builds the paywall around them, and your AI agent wires them together.

The two-tool workflow

The pattern:

gplay creates the Google Play subscription, base plans, offers, and per-country prices.
RevenueCat MCP registers those products, wraps them in an entitlement and offering, and generates a paywall referencing them.
RevenueCat MCP renders a screenshot for review.
You (or your agent) iterate on the paywall copy, re-render, repeat.

Every step is scriptable. The Google Play side is the ground truth; the paywall renders on top of that truth.

Full example: launching a “Pro” paywall

Step 1 — create the Play-side subscription with gplay

gplay subscriptions create \
  --package com.example.app \
  --product-id pro \
  --listing en-US:title="Pro",description="Unlimited access"

gplay baseplans create \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --billing-period P1M \
  --auto-renewing

gplay baseplans create \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id yearly \
  --billing-period P1Y \
  --auto-renewing

gplay baseplans prices set --region US --price-micros 9990000 \
  --subscription-id pro --base-plan-id monthly --package com.example.app
gplay baseplans prices convert --from-region US \
  --subscription-id pro --base-plan-id monthly --package com.example.app

gplay baseplans prices set --region US --price-micros 89990000 \
  --subscription-id pro --base-plan-id yearly --package com.example.app
gplay baseplans prices convert --from-region US \
  --subscription-id pro --base-plan-id yearly --package com.example.app

gplay offers create \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --offer-id monthly-trial-7d \
  --phases FREE_TRIAL,P7D,0

gplay subscriptions activate --package com.example.app --product-id pro

The Play-side is now real: pro:monthly at $9.99 with 7-day trial, pro:yearly at $89.99, PPP-converted across 175 countries.

Step 2 — prompt your AI agent to build the RC side + paywall

Open Claude Code (or Cursor, or any of the 12 supported agents) and prompt:

Using the RevenueCat MCP, wire up the “Pro” subscription for com.example.app and generate a paywall.

Products to register (Google Play): pro:monthly (subscription pro, base plan monthly) and pro:yearly (subscription pro, base plan yearly).

Create a “Pro” entitlement, attach both products. Create a “default” offering with $rc_monthly and $rc_annual packages.

Then generate a paywall:

Hero: “Try Pro free for 7 days”

Emphasize the yearly plan (25% savings vs monthly)

Feature list: read from README.md, take the top 4 items

Style: same brand palette as our existing “starter” paywall (get it from RC to reference)

Trust signal: “Join 50,000+ Pro users”

When done, render a screenshot and show it to me.

Step 3 — what the agent does

Chains of tool calls, roughly:

RC MCP create-product-in-store × 2 (monthly and yearly).
RC MCP create-entitlement “Pro”.
RC MCP attach-products-to-entitlement.
RC MCP create-offering “default”.
RC MCP create-packages ($rc_monthly, $rc_annual).
RC MCP attach-products-to-package.
cat README.md → extract feature list.
RC MCP list-paywalls → find “starter” → get-paywall for style reference.
RC MCP create-paywall-ai with the assembled brief → returns task ID.
RC MCP poll get-paywall-ai-task → wait ~30s.
RC MCP render-paywall-screenshot → PNG saved to ./paywalls/pro-launch.png.

You get back the screenshot. You look at it.

Step 4 — iterate

The magic isn’t the first render, it’s the second and third.

That looks great but the trial CTA is too subtle. Make it a persistent button at the bottom in accent color, and add “No commitment, cancel anytime” microcopy under it.

Agent calls RC MCP edit-paywall-ai with the change brief → new task → re-render.

Or:

Try three variants: the current one, one where yearly is the default selection, one with the testimonial replaced by a screenshot mockup. Render all three and show me side-by-side.

Agent chains create-paywall-ai three times with variant briefs → renders all three → shows you the grid.

Step 5 — ship it

When the paywall’s right, wire your app’s SDK to fetch it via RC’s Purchases.getOfferings(). Nothing else to configure — the paywall lives inside RC, references your products, which reference your gplay-created Play subscriptions. Every layer is real.

Verification

Before you ship, double-check the plumbing:

# 1. Play-side products actually exist and are active
gplay subscriptions get --package com.example.app --product-id pro

Prompt the agent:

Look up the RC customer for a sandbox test user, verify they can see the “default” offering with both packages, and that $rc_monthly price matches Google Play US ($9.99).

RC MCP get-customer → list-purchases → cross-reference with gplay baseplans prices list --region US.

If Play says $9.99 and RC says $9.99, you’re wired end-to-end.

Where this saves the most time

Marketing iteration. “Try a version with a countdown timer and social proof.” Fifteen seconds prompt to rendered variant. No designer round-trip.

Localized paywalls. “Generate the paywall in Japanese, French, and German using the Play Console’s localized offer names as the source of truth.” RC MCP creates variants; the agent pulls localized names via gplay offers locales list.

A/B test scaffolding. “Set up an experiment: 50% of new users get the current paywall, 50% get the countdown variant. Run for 2 weeks.” RC MCP list-experiments → create → assign traffic. Two weeks later, get-experiment-results and the agent summarizes.

Compliance rerender. “The Play Console policy team requires we show the auto-renew disclosure above the fold. Update every paywall in the account and re-render.” Loop of list-paywalls → edit-paywall-ai → render-paywall-screenshot.

Fastlane, gradle-play-publisher, hand-coded paywall builders

Not part of this workflow. Fastlane and gradle-play-publisher don’t touch monetization at all. Hand-coded paywalls (SwiftUI/Jetpack Compose views maintained in your app repo) mean every copy change is a code change, a build, a release. RC’s paywall system + gplay-created products means paywall changes are remote-configured, and product changes are one gplay command.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto

Set up the RevenueCat MCP with your RC secret key. Install the IAP setup skill:

npx skills add tamtom/gplay-cli-skills

Then prompt your agent to launch a subscription and paywall in one go. Full subscription reference at /reference/subscriptions/, offers at /reference/offers/, base plans at /reference/baseplans/.

Automate Google Play Console with Claude Code: a hands-on tutorial

Sun, 05 Jul 2026 00:00:00 GMT

Claude Code is Anthropic’s terminal-native AI coding agent. Combined with gplay — the AI-agent-native Google Play Console CLI — it’s the closest thing to a “release manager in a chat window” that Android publishing has ever had.

This tutorial shows the setup, the prompts that actually work, and what to watch out for.

Why gplay was built for agents like Claude Code

Before we plug them together, it’s worth calling out why this pairing is unusually clean:

gplay’s output is JSON by default. Claude Code parses it directly. No log scraping.
Every command has --help. Claude Code reads it when it needs to; the CLI is self-documenting.
Every write has --dry-run. Claude Code can preview a change before executing.
Explicit long flags — --package, --track, --rollout. Nothing ambiguous to hallucinate.
No interactive prompts. Destructive operations use --confirm, so Claude Code never has to answer a Y/N.

The result: Claude Code drives gplay reliably without a wrapper, MCP server, or shim. It’s just a CLI it can call.

One-time setup

1. Install gplay

brew install tamtom/tap/gplay

(Install script, Windows PowerShell, and manual binaries at /guides/installation/.)

2. Authenticate

gplay setup --auto

--auto handles the whole service-account dance: installs gcloud if missing, enables the Android Publisher API, creates a service account, downloads its key, invites it to your Play Console developer account. No dashboard-hunting.

3. Install the Agent Skills

npx skills add tamtom/gplay-cli-skills

This gives Claude Code 16 skills — release flow, staged rollouts, IAP setup, subscription localization, purchase verification, vitals monitoring, review management, screenshot automation, testers, metadata sync, Fastlane migration, pre-submission checks, and more.

Each skill is a small markdown file that teaches Claude Code the real Play Console workflow: what a track promotion actually looks like end-to-end, which validation to run before hitting Google, what to do when a rollout gets halted.

Example prompts that just work

The pattern is: describe the outcome, not the flags. Claude Code figures out the flags from --help and the skills.

Release an internal build and promote when green

Release app-release.aab to the internal track for com.example.app. Once it’s live and vitals look clean, promote it to closed alpha at 20% rollout.

Claude Code will:

Run gplay apps list to sanity-check access.
Run gplay release --track internal --bundle app-release.aab --package com.example.app.
Poll gplay tracks get --package com.example.app --track internal until the release status is completed.
Query gplay vitals crashes query --package com.example.app --time-range LAST_7_DAYS and compare against baseline.
If clean, run gplay tracks promote --package com.example.app --from internal --to alpha --rollout 0.2.

You watch it work. Every write it’s about to make, it says out loud. You approve or interrupt.

Update subscriptions from a spec file

Read subs.yaml — for each subscription, make sure the base plan exists at the listed price, create it if missing, and localize the offer name for en-US, fr-FR, de-DE, es-ES.

Claude Code will iterate: gplay subscriptions get, diff against the YAML, gplay baseplans create where needed, gplay offers create, gplay subscriptions locales set for each locale.

Fastlane can’t do that. gradle-play-publisher can’t do that. This is the entire monetization surface, driven by natural language.

Triage crash regressions

Grab this week’s top crash clusters. Compare user impact vs last week. If any cluster is over 500 users and up more than 30%, file a GitHub issue with the stack trace.

Claude Code chains gplay vitals crashes query, does the math itself, and calls gh issue create. It doesn’t need a separate observability tool — the Play Console API is the observability tool.

Reply to reviews

List all 1-star reviews from the last 14 days that mention “login”. Draft a reply for each and show me the list to approve before sending.

gplay reviews list --filter → per-review draft → --dry-run reply preview → you approve → gplay reviews reply. Zero clicks in the Play Console web UI.

Guardrails: how to keep it safe

A few habits that make this pairing feel controlled instead of chaotic:

Use --dry-run in the prompt. For anything you’re not sure about: “…do it as --dry-run first and show me the payload.” gplay intercepts every write HTTP method and logs the request to stderr without executing. Claude Code will echo the payload back to you before actually running.

Give it a scoped service account. Run gplay under a service account that’s granted only the Play permissions it needs (or a per-app grant instead of account-wide). If Claude Code goes off-script, the blast radius is bounded to what that account can touch.

Use an edit session for related changes. gplay edit begin starts a transactional edit; multiple changes commit atomically with gplay edit commit. If Claude Code is doing a multi-step listing update and something looks off, gplay edit cancel throws it all away.

Read the diff. Every write, Claude Code shows you the exact command. Read it before approving. Same rule as reviewing a PR.

What about Cursor, OpenClaw, Hermes Agent, Codex, Gemini CLI…?

Same story. gplay’s design isn’t Claude-specific — it works with every major AI coding agent of 2026: Claude Code, Cursor, Codex, Gemini CLI, Aider, Cline, Windsurf, Continue, GitHub Copilot CLI, OpenClaw, Hermes Agent, Amazon Q Developer. The Agent Skills package is the same one-liner for all of them.

The reason we lead with Claude Code in tutorials is that its terminal-native design lets it invoke a CLI directly without an MCP wrapper or plugin layer — the shortest path from prompt to gplay tracks promote.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
npx skills add tamtom/gplay-cli-skills

Then open Claude Code in the project you want to release from and try:

What can you do with gplay for com.example.app?

It’ll enumerate the surface and offer a starting point. Take it from there.

Full reference at /reference/, guides at /guides/.

Automate your full mobile subscription stack: Claude Code + RevenueCat MCP + gplay

Sun, 05 Jul 2026 00:00:00 GMT

Historically, launching a new mobile subscription tier meant a checklist across three or four dashboards: Play Console for the Android product, App Store Connect for iOS, RevenueCat for entitlements and offerings, some paywall builder for the UI. Each dashboard has its own click paths, its own idempotency semantics, its own way to be wrong.

With Claude Code, the RevenueCat MCP server, and gplay, the whole thing becomes one prompt.

The setup

Three ingredients:

Claude Code — Anthropic’s terminal-native AI coding agent. Reads your project, calls tools, writes code.
RevenueCat MCP — the RevenueCat team’s Model Context Protocol server. Exposes entitlements, offerings, packages, products, paywalls, customers, and revenue analytics as callable tools.
gplay — the AI-agent-native Google Play Console CLI. Covers 250+ commands across 6 Google APIs, JSON-first, --dry-run on every write.

Install:

# gplay
brew install tamtom/tap/gplay
gplay setup --auto

# Agent Skills so Claude Code knows the real Play workflows
npx skills add tamtom/gplay-cli-skills

RevenueCat MCP setup: follow their docs. Adds a block to your Claude Code config that registers the MCP server with your RC secret key.

What Claude Code can now do

Every RevenueCat MCP tool + every gplay command + gh, git, your Gradle build. The intersection is powerful.

Here’s a session that stood up a real subscription tier in one prompt (transcript compressed).

The prompt

Launch a new “Pro” subscription for com.example.app:

Monthly at $9.99 with a 7-day free trial for new users, PPP prices to all supported countries.

Yearly at $89.99 (25% saving vs monthly).

Register both as Play products, then map into RevenueCat as a “Pro” entitlement, an “default” offering with $rc_monthly and $rc_annual packages.

Generate an AI paywall — hero: “Unlock Pro”, features from the app’s README, testimonial style similar to our existing “starter” paywall.

Add a targeting rule: users on our existing “starter” entitlement get shown a “$rc_annual” upsell offering instead of “default”.

Show me the final paywall screenshot and a summary of what you shipped. Don’t actually flip anything live — use --dry-run for the Play writes so I can review.

What Claude Code did (chained tool calls)

gplay apps list → confirmed access to com.example.app.
gplay subscriptions create --product-id pro --listing en-US:... (dry-run) → showed the JSON payload.
gplay baseplans create --base-plan-id monthly --billing-period P1M ... (dry-run) for both plans.
gplay baseplans prices set --region US --price-micros 9990000 → then gplay baseplans prices convert --from-region US.
gplay offers create --offer-id monthly-trial-7d --phases FREE_TRIAL,P7D,0.
RC MCP create-product-in-store → registered pro:monthly and pro:yearly.
RC MCP create-entitlement → “Pro”.
RC MCP attach-products-to-entitlement → linked both products.
RC MCP create-offering “default” → create-packages for $rc_monthly and $rc_annual → attach-products-to-package.
cat README.md → extracted feature list for the paywall copy.
RC MCP list-paywalls → found existing “starter” paywall → get-paywall for style reference.
RC MCP create-paywall-ai with the description → returned task ID.
RC MCP poll get-paywall-ai-task → 30s later, complete.
RC MCP render-paywall-screenshot → saved PNG to ./paywalls/pro-launch.png.
RC MCP list-targeting-rules → confirmed “starter” entitlement exists.
RC MCP create targeting rule: entitlement=starter → assign-customer-offering annual-upsell.
Printed a summary table of everything created + the paywall screenshot.

You read the dry-run payloads. If they look right, you say “go” and Claude Code re-runs step 2-9 for real (drops --dry-run from the gplay commands; RC MCP calls are idempotent).

Where this pays off long-term

The one-prompt launch is the flashy demo. The real value shows up in the ongoing operations.

Weekly business review, prompt-driven:

Pull the last 7 days of RevenueCat overview metrics. For any product with >10% trial-to-paid drop-off vs the previous week, cross-reference with gplay’s vitals — are there crashes on the paywall screen? Rank issues by revenue impact and file GitHub issues for the top three.

Chains: RC MCP get-overview-metrics → RC MCP get-chart-data for trial cohorts → gplay vitals crashes query filtered to specific screens → RC MCP get-benchmarks for industry context → gh issue create.

Price experiments, safely:

Add a targeting rule: 10% of new Indian users get the “budget” offering with a ₹299 monthly price. Everyone else stays on default. Wire it up in RC and make sure the ₹299 monthly base plan actually exists on Google Play (create it if not).

Chains: gplay baseplans list → conditional baseplans create → gplay baseplans prices set --region IN → RC MCP create-offering “budget” → create-targeting-rule.

Refund reconciliation:

Pull the last 24 hours of Google Play voided purchases. For each, revoke the RevenueCat entitlement grant for that customer.

Chains: gplay purchases voided list --start-time <24h ago> → for each: RC MCP get-customer by originalTransactionId → RC MCP revoke grant.

Why the pairing works so well

Both surfaces are agent-native, but they cover different territory:

gplay is the writer of truth. It manipulates Play Console state directly. When you need something to actually exist in Google Play, gplay does it.
RC MCP is the reader of state. It sees your Play products (via RC’s own webhooks + polling), aggregates the cross-store view, and lets the agent reason about entitlements/customers/revenue across iOS and Android.

Neither alone gets you to “one-prompt launch.” Together they do.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
npx skills add tamtom/gplay-cli-skills

Add the RevenueCat MCP to your Claude Code config with your RC secret key. Then open Claude Code in your Android project and try:

Show me every subscription on Google Play for com.example.app, then show me the matching RevenueCat entitlements and offerings. Any drift?

The answer to that question was previously a 30-minute audit across two dashboards. Now it’s a prompt.

Diagnose your Play Console access with gplay auth doctor

Sun, 05 Jul 2026 00:00:00 GMT

Google Play API authentication is a small forest of things that can go wrong. Your service account might exist but not have the Android Publisher API enabled on its GCP project. It might be invited to your Play Console developer account but not accepted yet. Its key might be expired. Its scopes might be missing a permission you added recently.

Debugging any of these by hand is slow. gplay auth doctor runs every check in one shot.

What it checks

gplay auth doctor

Output (all-green case):

✓ Service account file readable at /Users/you/.gplay/keys/play-sa.json
✓ Service account email: play-cli@my-project.iam.gserviceaccount.com
✓ Client ID present
✓ Private key valid (RSA 2048)
✓ GCP project 'my-project' exists
✓ Android Publisher API enabled on my-project
✓ Reporting API enabled on my-project (needed for vitals)
✓ Service account accepted in Play Console developer account 4571234567890
✓ Developer role: Admin (Access all apps)
✓ Test API call: gplay apps list → 3 apps returned
✓ Configuration:
    default_package: com.example.app
    timeout: 120s
    upload_timeout: 5m

Everything looks good.

Any red or yellow line tells you exactly which step is broken. No more guessing.

Common failure modes

“Android Publisher API not enabled”

✗ Android Publisher API NOT enabled on my-project
  → Enable it: https://console.cloud.google.com/apis/library/androidpublisher.googleapis.com?project=my-project
  → Or run: gplay auth doctor --fix

--fix --confirm will call the GCP API to enable it for you:

gplay auth doctor --fix --confirm

Takes about 30 seconds to propagate.

“Service account not accepted in Play Console”

✗ Service account play-cli@my-project.iam.gserviceaccount.com found in Play Console
  invitation list but not accepted.
  → Open https://play.google.com/console/u/0/developers/4571234567890/users-and-permissions
    and click Accept next to this email.

This one is manual — Google requires a human accept the developer-account invite. gplay tells you exactly where to click.

“Developer role has insufficient permissions”

⚠ Developer role: Marketing (Access some apps)
  → Reason: your role can read listings but not tracks. Some gplay commands will fail.
  → Fix: escalate role in Play Console, or grant per-app permissions
    (gplay grants create --package com.example.app --permissions ...)

Some commands need admin, some need track edit. auth doctor flags the gap without waiting for a specific command to fail.

“Reporting API not enabled”

Only matters if you use gplay vitals:

⚠ Play Developer Reporting API NOT enabled — vitals commands will fail
  → Fix: gplay auth doctor --fix --confirm

“Private key expired or rotated”

✗ Private key rejected by Google (invalid_grant)
  → The key at /Users/you/.gplay/keys/play-sa.json is likely rotated or revoked
  → Fix: gplay auth login --service-account /path/to/new-key.json

You’ll see this the day someone in your org enforces the 90-day key rotation policy.

“Timeout too aggressive for uploads”

⚠ upload_timeout is 30s — AAB uploads over slow networks may fail
  → Recommended: 5m or higher via GPLAY_UPLOAD_TIMEOUT or ~/.gplay/config.yaml

Fix flags

--fix proposes remediations. --confirm executes them non-interactively (needed in CI). Together:

gplay auth doctor --fix --confirm

What --fix can do without asking:

Enable Android Publisher API on the linked GCP project.
Enable Play Developer Reporting API.
Update ~/.gplay/config.yaml timeouts to safer defaults.

What it won’t do (needs a human):

Accept a Play Console developer invitation (Google policy).
Rotate a service-account key (you should verify).
Escalate a developer role (permissions change).

CI usage

Run it as the first step of your release pipeline. If auth is degraded, fail early:

- name: Verify Play API auth
  env:
    GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
  run: gplay auth doctor --output json | jq -e '.status == "healthy"'

--output json returns a structured verdict with per-check pass/fail. jq -e fails the step if the overall status isn’t healthy.

Beats a Play API call failing 20 minutes into an upload.

Alongside a new service account

The order of operations setup --auto runs, if you want to know what doctor is checking:

Detect or install gcloud.
Prompt for or create a GCP project.
Enable Android Publisher API and Reporting API on that project.
Create service account.
Download JSON key to ~/.gplay/keys/.
Print the service-account email and ask you to invite it in Play Console.

gplay auth doctor re-validates steps 3-6 any time you run it.

When to run it

After gplay setup --auto — sanity check.
When your CI job starts failing with invalid_grant or unauthorized.
After rotating a key.
After adding a new API (subscriptions → in-app products → reporting).
Weekly as a cron in a lightweight monitoring workflow.
Before assuming “gplay is broken” — it’s usually auth.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay auth doctor

If you get a red line, read what it says — that’s where the fix is. If you’re not sure, gplay auth doctor --fix --confirm handles the fixable ones automatically. Full auth reference at /reference/auth/, full setup at /guides/authentication/.

Google Play ASO: from keyword research to submission with gplay and an AI agent

Sun, 05 Jul 2026 00:00:00 GMT

App Store Optimization on Google Play is where a well-worded title, a keyword-rich short description, and localized long descriptions turn into installs. It’s also traditionally where the most tedious mobile-marketing work happens: research competitor keywords, audit your current listings, draft variants, translate, get approvals, click through the Play Console to update each locale, wait, ship.

The gplay CLI plus an AI agent collapses this into a single afternoon workflow. Here’s how.

Overview

The four phases of a Play ASO cycle:

Research — what keywords should you rank for, and how do competitors position?
Audit — what does your current listing look like, per locale, across all supported markets?
Optimize — draft revised titles, short descriptions, long descriptions, and localize them.
Ship — push the changes atomically inside an edit session and monitor rankings.

gplay covers phases 2 and 4 directly, and enables phases 1 and 3 by giving your AI agent structured data to reason about.

Phase 1 — research (agent-assisted)

Give your AI agent a research prompt:

I want to improve ASO for com.example.app — a habit-tracking app that competes with Streaks, Habitica, and Way of Life. Research the top 20 keyword phrases those competitors’ listings target on Google Play. For each keyword, note whether it’s in the title, short description, or long description, and estimate search intent volume qualitatively. Return a ranked list with rationale.

Any of the 12 supported agents with web-browsing (Claude Code, Cursor, ChatGPT with browsing, etc.) can do the competitor scan. You get back a ranked keyword list — the raw material for phase 3.

Phase 2 — audit your current listings

Pull every locale you currently ship in:

gplay listings list --package com.example.app --output table

Then export each locale’s listing to JSON for the agent to inspect:

mkdir -p ./aso-audit
gplay listings list --package com.example.app \
  | jq -r '.[].language' \
  | while read LOCALE; do
      gplay listings get --package com.example.app --locale $LOCALE \
        > "./aso-audit/${LOCALE}.json"
    done

Now your agent has a per-locale snapshot. Prompt:

Read every JSON file in ./aso-audit/. For each locale, tell me:

Does the current title include any of the top keywords from the research doc?

Is the short description using its full 80-character budget?

Is the long description repeating any keyword more than 3 times (over-optimization penalty risk)?

Rank locales by improvement potential (biggest gap between current and ideal).

You get a per-locale gap analysis in one pass.

Phase 3 — optimize copy per locale

For your top-priority locale (usually en-US), prompt:

Rewrite the en-US title, short description, and full description for com.example.app to target the top 5 keywords from research. Constraints: title ≤ 30 chars, short description ≤ 80 chars, full description ≤ 4000 chars. Preserve the “gentle, non-nagging” brand voice from the current listing. Return three variants of each.

Pick the variant you like. Then propagate to other locales:

Take the chosen en-US variant and translate it into fr-FR, de-DE, es-ES, es-419, pt-BR, ja-JP, ko, zh-CN, zh-TW, and ar. Preserve keyword semantic intent — don’t just literally translate the keywords, use whatever people search for in that language. Note per-locale where the keyword substitution changes character count materially.

Write results to metadata/<locale>/.

Phase 4 — dry-run, review, ship

Preview what will be sent to Play:

gplay listings push \
  --package com.example.app \
  --listings-dir ./metadata \
  --dry-run

Diff against production to double-check:

# Save current state
gplay listings list --package com.example.app \
  | jq -r '.[].language' \
  | while read L; do
      gplay listings get --package com.example.app --locale $L \
        > "./aso-audit/before-${L}.json"
    done

# Compare against your metadata/ files with jq or diff

Ship inside an edit session so everything commits atomically:

gplay listings push \
  --package com.example.app \
  --listings-dir ./metadata

If anything fails mid-way, gplay discards the edit — the Play Console goes back to exactly its previous state, no partial half-updated locales.

Post-ship: monitor rankings

Google doesn’t expose keyword-rank APIs, so the honest answer is: install rankings tracking (App Radar, AppTweak, Sensor Tower) and correlate the rank change to your ship date. gplay can’t do this piece.

What gplay can do is monitor install/impression trends via gplay reports statistics:

# Install statistics report
gplay reports statistics list --package com.example.app

gplay reports statistics download \
  --package com.example.app \
  --report-type INSTALLS \
  --year 2026 --month 7 \
  --output ./reports/

Compare month-over-month against your ship date. Not as precise as a rank tracker but free and useful.

The full end-to-end workflow, as a single prompt

Once you’ve done this cycle once by hand, you can compress it. In Claude Code:

Run a Google Play ASO audit for com.example.app:

Pull every current listing to ./aso-audit/.

Web-research the top 20 keywords the top 5 habit-tracking apps target on Play (Streaks, Habitica, Way of Life, Loop, Done).

Rank my locales by improvement potential.

For the top 3 locales, draft 3 title/short/long description variants each.

Wait for me to pick the winners.

Translate winners to the remaining locales.

Dry-run gplay listings push and show me the payload.

Wait for my approval, then push.

Use the metadata-sync skill from tamtom/gplay-cli-skills for the file layout.

An afternoon’s worth of clickwork becomes a review session.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
npx skills add tamtom/gplay-cli-skills

Full listings reference at /reference/listings/. For deeper locale handling see Managing 80+ Google Play locales from the terminal.

The ASO cycle is where CLIs and AI agents together outperform every other workflow — the tedious parts (audit, translate, push) are exactly the parts machines do best, and the judgment parts (brand voice, keyword tradeoffs) stay with you.

gplay vs gradle-play-publisher: which is the better Google Play CLI in 2026?

Sun, 05 Jul 2026 00:00:00 GMT

If you build Android apps with Gradle, gradle-play-publisher (GPP) has probably crossed your radar as the way to publish to Google Play without leaving your build script. It’s a solid, focused tool. But if you’ve ever needed to do anything on Play Console beyond uploading an AAB and updating a listing — subscriptions, purchase verification, crash reports, reviews, reports — you’ve hit its ceiling.

gplay takes a different bet: one static binary, all of Play Console.

The short version

GPP is Gradle-native. If your entire release flow lives inside ./gradlew, it fits naturally: ./gradlew publishRelease and you’re done.
gplay is Play Console-complete. Subscriptions with base plans and offers, in-app products, purchase verification, vitals (crashes, ANRs, startup, battery), reviews, financial reports, users and permissions, Managed Google Play custom apps, Google Checks compliance — 250+ commands across 6 Google APIs.
Different runtime shape. GPP is a Gradle plugin (JVM, needs your build project). gplay is a static Go binary — no runtime, works from any shell, any container, any language.

Feature comparison

Capability	gplay	gradle-play-publisher
Upload AAB/APK to tracks	✅	✅
Staged rollouts (fractional)	✅	✅
Promote between tracks	✅	✅
Store listings (title, description, graphics)	✅	✅
Screenshots	✅	✅
Release notes per track and locale	✅	✅
Deobfuscation & native debug symbols	✅	✅
Subscriptions (base plans, offers, prices)	✅ Full	❌
In-app products	✅	❌
Server-side purchase verification	✅	❌
Vitals: crashes, ANRs, performance	✅	❌
Reviews (list + reply)	✅	❌
Financial & statistics reports (GCS)	✅	❌
Users & permission grants	✅	❌
Managed Google Play custom apps	✅	❌
Google Checks compliance	✅	❌
Runtime	Single 12MB Go binary	Gradle plugin (JVM + build)
Works outside the Android project	✅	⚠️ Needs Gradle context
JSON-first output for agents/scripts	✅	❌ (Gradle output)
`--dry-run` on writes	✅	⚠️ Task-level only

GPP covers the “publish a build” story well. Where gplay pulls ahead is everything after publish: monitor how it’s doing, monetize it, keep it compliant, respond to users.

When GPP is the right pick

Pick gradle-play-publisher if all of these are true:

Your release flow lives entirely inside Gradle and you like it that way.
You publish AABs and update listings — no subscriptions, no purchase verification, no vitals monitoring from CI.
Your Play Console work outside of ./gradlew publishRelease is done manually in the web UI, and you’re happy with that split.

That’s a real use case. If it’s yours, GPP is well-designed for it.

When gplay is the right pick

Pick gplay if any of these are true:

You have subscriptions, in-app products, or offers to manage — GPP does not cover monetization at all.
You want to verify purchases server-side without pulling in the full Google API Java client and OAuth boilerplate.
You want to check crashes, ANRs, or performance metrics from CI (fail the pipeline on regressions).
You reply to reviews or download reports as part of your release ritual.
You’re driving Play Console from an AI coding agent (Claude Code, Cursor, OpenClaw, Hermes Agent) — gplay’s JSON-first output, explicit long flags, --dry-run, and --help discoverability are built for agents. GPP was not.
You want the same tool to work on macOS, Linux CI, Windows PowerShell, and inside minimal Docker containers — no JVM, no Gradle, no project context needed.
You’re using something other than Gradle (Bazel, Buck, custom build scripts, Kotlin Multiplatform with non-Gradle targets).

Can you use both?

Yes. A common pattern: GPP handles the “upload from ./gradlew” step for developer ergonomics, and gplay handles everything else in CI — post-release rollout monitoring, subscription changes, crash alerts, review replies, monthly report downloads.

They don’t conflict. They read the same service account. Nothing stops you from using GPP for uploads and gplay for the rest.

Runtime footprint

This one is easy to overlook until you feel it.

gradle-play-publisher runs inside your Gradle build: JVM startup, plugin resolution, project sync. On a Mac laptop that’s a few seconds; on a cold CI runner it can be 30-60 seconds before the first upload byte moves.
gplay is a 12 MB static Go binary. Cold-start is under 50 ms. In a minimal alpine:latest container, gplay tracks list returns before Gradle has finished parsing your build.gradle.

For an agent that runs dozens of Play API calls in a single session (checking crashes, updating listings, promoting rollouts) the difference compounds.

The AI-agent angle

If you’re using an AI coding agent (Claude Code, Cursor, Codex, Gemini CLI, Aider, Cline, Windsurf, Continue, GitHub Copilot CLI, OpenClaw, Hermes Agent), gplay was designed for you:

JSON output by default — the agent parses it directly, no scraping.
Explicit long flags — --package, --track, --rollout; no ambiguous short flags to hallucinate.
--help on every command — agents discover the surface instead of guessing.
--dry-run on every write — safe preview before executing.
No interactive prompts — nothing blocks on stdin.
16 ready-made Agent Skills — install with npx skills add tamtom/gplay-cli-skills and your agent knows the real Google Play workflows.

GPP’s output is Gradle task output. An agent trying to drive it has to parse human-facing logs. It works, but it’s fragile.

Try gplay in one command

brew install tamtom/tap/gplay
gplay setup --auto   # installs gcloud, enables the API, creates a service account
gplay apps list      # you're already in

Full install options (Homebrew, install script, Windows PowerShell, manual binaries) on the installation page. Full command reference at /reference/.

If you’re on GPP today and want to see what “the rest of Play Console” looks like, start with these three: gplay vitals crashes query, gplay subscriptions list, and gplay reviews list. Chances are you’ll find a workflow you were doing in the web UI that suddenly belongs in CI.

How to release an Android app to Google Play from the terminal

Sun, 05 Jul 2026 00:00:00 GMT

Publishing to Google Play traditionally means clicking through the Play Console web UI: create a release, drag in an AAB, paste release notes, pick a rollout percentage, review, confirm. It works — but it’s slow, unscriptable, and impossible to automate.

Under the hood, though, every one of those clicks maps to the Google Play Developer API’s edit-session model. gplay wraps that whole model into commands you can run from your terminal or CI. Here’s the complete flow.

Prerequisites

Install gplay — one static binary, via Homebrew or install script
Authenticate — gplay setup --auto does the whole service-account dance for you
A built AAB (see your Gradle setup or CI pipeline)

The one-command release

gplay release --package com.example.app --track internal --bundle app.aab

That single command creates an edit session, uploads the bundle, assigns the version to the internal track, and commits the edit. If any step fails, nothing is applied — edits are atomic.

Production, with release notes and a staged rollout

gplay release --package com.example.app --track production \
  --bundle app.aab \
  --release-notes @notes.json \
  --rollout 0.1

Two things worth knowing:

--rollout is a fraction between 0.0 and 1.0 — 0.1 means 10% of users. (Not 10!)
--release-notes takes a JSON file with per-locale notes, or plain text that’s auto-assigned to en-US.

An example notes.json:

[
  { "language": "en-US", "text": "Bug fixes and performance improvements." },
  { "language": "de-DE", "text": "Fehlerbehebungen und Leistungsverbesserungen." }
]

You can even generate the notes from your git history:

gplay release-notes generate

Watch and expand the rollout

# Where is the rollout right now?
gplay rollout status --package com.example.app --track production

# Expand 10% → 50%
gplay rollout update --package com.example.app --track production --rollout 0.5

# Crash spike? Halt immediately.
gplay rollout halt --package com.example.app --track production

# All good — ship to everyone
gplay rollout complete --package com.example.app --track production

Pair this with gplay vitals crashes to gate each expansion on real crash data.

Promote instead of re-uploading

Once a build has soaked on internal or beta, don’t upload it again — promote the exact same artifact:

gplay promote --package com.example.app --from beta --to production --rollout 0.1

Try everything safely first

Every write command supports --dry-run, which logs the HTTP requests it would make without executing them:

gplay --dry-run release --package com.example.app --track production --bundle app.aab

This is also what makes gplay safe to hand to an AI agent or a new CI pipeline — you can see exactly what would happen before it does.

The same flow in CI

# GitHub Actions
- name: Release to internal
  env:
    GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
    GPLAY_PACKAGE: com.example.app
  run: gplay release --track internal --bundle app/build/outputs/bundle/release/app-release.aab

No Ruby, no Gradle plugin configuration — the same binary and the same command you ran locally.

Next steps

Quickstart guide — the 5-minute tour
Command reference — every command and flag
Use gplay with AI agents — let your agent run the release

Managing 80+ Google Play locales from the terminal

Sun, 05 Jul 2026 00:00:00 GMT

Google Play supports more than 80 store-listing locales — from af (Afrikaans) to zu (Zulu), including regional variants like es-419 (Latin American Spanish), pt-BR (Brazilian Portuguese), and zh-TW (Traditional Chinese). Setting them all up in the Play Console web UI means clicking through a language dropdown once per locale, per app, and re-doing it for every listing change.

gplay turns that into a scriptable batch job. Here’s the full toolkit.

Discover the supported locales

gplay listings locales

Returns the full list Google Play accepts, as JSON:

[
  { "code": "af", "name": "Afrikaans" },
  { "code": "am", "name": "Amharic" },
  { "code": "ar", "name": "Arabic" },
  { "code": "az-AZ", "name": "Azerbaijani" },
  ...
  { "code": "zh-TW", "name": "Chinese (Traditional)" },
  { "code": "zu", "name": "Zulu" }
]

Or as a table:

gplay listings locales --output table

Validate a code before you use it (avoid typos wasting a Play API round-trip):

gplay listings locales --validate ar-XB
# → error: unknown locale 'ar-XB'. Did you mean 'ar'?

See what you currently have

Which locales does your app currently have listings for?

gplay listings list --package com.example.app --output table

Diff against the full supported set to find gaps:

CURRENT=$(gplay listings list --package com.example.app | jq -r '.[].language' | sort)
SUPPORTED=$(gplay listings locales | jq -r '.[].code' | sort)
comm -23 <(echo "$SUPPORTED") <(echo "$CURRENT")

That tells you exactly which of the 80+ locales you’re missing.

Get a single locale’s full listing

gplay listings get \
  --package com.example.app \
  --locale de-DE

Returns title, short description, full description, video URL. Perfect for pulling translations into a review tool.

Bulk-create listings from a directory

The --listings-dir flag reads Fastlane-format metadata:

metadata/
├── en-US/
│   ├── title.txt
│   ├── short_description.txt
│   ├── full_description.txt
│   └── changelogs/default.txt
├── fr-FR/
│   └── ...
├── de-DE/
├── es-ES/
├── ja-JP/
├── ko/
├── pt-BR/
└── zh-TW/

Push them all in one shot:

gplay listings push \
  --package com.example.app \
  --listings-dir ./metadata

Every locale that has a directory gets its listing created or updated inside a single edit session — atomic commit.

Preview before pushing

--dry-run intercepts the write and shows you the payload:

gplay listings push \
  --package com.example.app \
  --listings-dir ./metadata \
  --dry-run

You see exactly what will be sent to Google, per locale, without touching production.

Per-locale release notes

Release notes shipped alongside a track update. YAML format:

release-notes.yaml

en-US: "New Pro features and bug fixes"
en-GB: "New Pro features and bug fixes"
fr-FR: "Nouvelles fonctionnalités Pro et corrections de bugs"
de-DE: "Neue Pro-Funktionen und Fehlerbehebungen"
es-ES: "Nuevas funciones Pro y correcciones de errores"
es-419: "Nuevas funciones Pro y correcciones de errores"
pt-BR: "Novas funcionalidades Pro e correções de bugs"
ja-JP: "新しいProの機能とバグ修正"
ko: "새로운 Pro 기능 및 버그 수정"
zh-TW: "新 Pro 功能與錯誤修正"
zh-CN: "新 Pro 功能与错误修复"
ar: "ميزات Pro الجديدة وإصلاحات الأخطاء"

Apply on release:

gplay release \
  --package com.example.app \
  --track internal \
  --bundle app-release.aab \
  --release-notes-file release-notes.yaml

Or generate the whole file from git history in your default locale, then translate:

gplay release-notes generate --since v4.1.0 --output release-notes.yaml

If you pass a plain string as --release-notes, gplay auto-assigns it to en-US. Explicit is better — but this shortcut is handy for internal builds.

Locale-aware validation

Google will reject a release if:

Any locale has an empty title.
Full description exceeds 4,000 characters.
Short description exceeds 80 characters.
A locale exists in your listings but not in the supported set (typo, stale data).

Preflight:

gplay listings validate \
  --package com.example.app \
  --listings-dir ./metadata

AI-agent-driven localization

Combine gplay with your AI agent for the tedious parts. Prompt:

Pull the en-US listing and full description for com.example.app. Translate the short and full descriptions into French, German, Spanish (both es-ES and es-419), Portuguese (both pt-BR and pt-PT), Japanese, Korean, Chinese (both zh-CN and zh-TW), and Arabic. Preserve technical terms (product names, feature names). Write each to metadata/<locale>/short_description.txt and full_description.txt. When done, dry-run gplay listings push so I can review.

Chains: gplay listings get --locale en-US → LLM translations to files → gplay listings push --dry-run. You review, then run without --dry-run.

Every one of the 12 supported agents — Claude Code, Cursor, Codex, Gemini CLI, Aider, Cline, Windsurf, Continue, GitHub Copilot CLI, Amazon Q Developer, OpenClaw, Hermes Agent — can do this. Install the metadata-sync skill and they’ll know the file layout by default.

Screenshots per locale

Localized listings often need localized screenshots (screenshots with translated in-image text). gplay listings push --screenshots-dir reads the same Fastlane-format tree:

screenshots/
├── en-US/
│   └── phoneScreenshots/
│       ├── 1.png
│       ├── 2.png
│       └── ...
├── fr-FR/
│   └── phoneScreenshots/
│       └── ...

Or use --skip-screenshots if you only want to update text.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay listings locales --output table
gplay listings list --package com.example.app --output table

Full listings reference at /reference/listings/. If you’re maintaining a large locale matrix, install the metadata-sync skill and let your AI agent drive the day-to-day translation-review-push cycle.

Migrate from Fastlane supply to gplay in an afternoon

Sun, 05 Jul 2026 00:00:00 GMT

If you’ve been shipping Android with Fastlane for years, you have a directory tree that looks something like:

fastlane/
├── Fastfile
└── metadata/
    └── android/
        ├── en-US/
        │   ├── title.txt
        │   ├── short_description.txt
        │   ├── full_description.txt
        │   ├── images/
        │   │   ├── icon.png
        │   │   ├── featureGraphic.png
        │   │   └── phoneScreenshots/
        │   └── changelogs/
        │       └── default.txt
        └── fr-FR/
            └── ...

Good news: gplay reads this format directly. You don’t have to rewrite your metadata, re-download screenshots, or manually re-enter listings. This post walks through the full migration in an afternoon.

Step 1 — install gplay

brew install tamtom/tap/gplay
gplay setup --auto
gplay apps list

setup --auto reuses your existing service account if you already have one, or creates a new one. apps list confirms the connection.

Step 2 — dry-run your existing metadata

gplay migrate fastlane reads fastlane/metadata/android/ and shows you exactly what will be uploaded, without touching anything:

gplay migrate fastlane \
  --package com.example.app \
  --metadata-dir fastlane/metadata/android \
  --dry-run

Output (formatted for readability):

Locale: en-US
  title: "MyApp"
  short_description: 80 chars
  full_description: 3120 chars
  screenshots (phone): 6 images
  featureGraphic: 1024x500
  changelog: 240 chars

Locale: fr-FR
  ...

Total: 12 locales, 68 screenshots, 12 changelogs
Total upload size: 41 MB

Read the diff. If anything looks wrong (missing locale, oversized screenshot, empty changelog), fix the source files first. gplay does not truncate — it fails loudly on Google’s validation.

Step 3 — run the migration

Drop the --dry-run:

gplay migrate fastlane \
  --package com.example.app \
  --metadata-dir fastlane/metadata/android

This creates an edit session, uploads every listing, screenshot, and changelog, then commits atomically. If anything fails mid-way, the edit is discarded — Play Console goes back to exactly its previous state.

Step 4 — replace your supply lane

Your Fastfile probably has something like:

lane :deploy do
  gradle(task: "bundleRelease")
  supply(
    track: "internal",
    aab: "app/build/outputs/bundle/release/app-release.aab",
    metadata_path: "./fastlane/metadata/android",
    skip_upload_apk: true
  )
end

The gplay equivalent:

./gradlew bundleRelease
gplay release \
  --package com.example.app \
  --track internal \
  --bundle app/build/outputs/bundle/release/app-release.aab \
  --listings-dir fastlane/metadata/android

--listings-dir reuses your existing Fastlane metadata directory on every release. No migration needed for future runs — the source of truth stays where it is.

Or point it at a different directory if you want to move it out of the fastlane/ folder later:

gplay release \
  --package com.example.app \
  --track internal \
  --bundle app-release.aab \
  --listings-dir play-metadata

Step 5 — port your other supply lanes

Every Fastlane action has a gplay equivalent. The ones you probably use most:

Fastlane	gplay
`supply(track: "internal", aab: "...")`	`gplay release --track internal --bundle ...`
`supply(track: "production", rollout: "0.1")`	`gplay tracks promote --to production --rollout 0.1`
`supply(skip_upload_screenshots: false, ...)`	`gplay release --listings-dir ...`
`download_screenshots(...)`	`gplay listings pull --output-dir ...`
`upload_to_play_store_internal_app_sharing`	`gplay internal-app-sharing upload --bundle ...`
Manual: change track from internal to alpha	`gplay tracks promote --from internal --to alpha`
Manual: check listing status	`gplay listings get --package ... --locale en-US`

Step 6 — bonus, do things you couldn’t before

Once you’ve migrated, you have 250+ commands available that Fastlane supply doesn’t cover. A few worth trying immediately:

Check crashes from CI:

gplay vitals crashes query --package com.example.app --time-range LAST_7_DAYS

Reply to reviews:

gplay reviews list --filter "rating<=2"
gplay reviews reply --review-id <id> --message "Thanks for the feedback..."

Manage subscriptions:

gplay subscriptions list
gplay baseplans list --subscription-id monthly_pro

Download this month’s earnings:

gplay reports financial list
gplay reports financial download --report-id earnings_202607

Fastlane can’t do any of this. It’s not a bug — supply was designed for a narrower job. gplay wasn’t.

What you can leave in place

You don’t have to rip Fastlane out. Common hybrid:

Keep Fastlane for the parts of iOS release you already have working.
Keep fastlane/metadata/android/ as the source of truth for listings (gplay reads it natively).
Use gplay for Android release, staged rollout, monitoring, subscriptions, purchase verification, and everything post-publish.

Rollback plan

If you decide the migration didn’t work out (it will, but hypothetically):

Your Fastlane metadata directory is unchanged. gplay reads it; it doesn’t rewrite it.
Your service account and Play Console access are unchanged. Fastlane still authenticates fine.
Your CI can call both. Nothing is exclusive.

Reverting is git revert on the workflow change. Zero data loss.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay migrate fastlane --package com.example.app --metadata-dir fastlane/metadata/android --dry-run

Full migration reference at /reference/migrate/. If you want to fully automate the migration and CI rewrite in one shot, install the Fastlane migration skill and ask your AI agent to walk your repo end-to-end.

Monitor Google Play crashes and ANRs from the terminal (or CI)

Sun, 05 Jul 2026 00:00:00 GMT

Play Console’s vitals dashboards are fine for eyeballing trends. They’re less good when you want to:

Fail a CI job if the new release’s crash rate is 30% above baseline.
Post a Slack alert when a new crash cluster affects more than 500 users.
Diff this week’s ANRs against last week’s before promoting to production.
Have your AI agent triage the top 10 clusters and file GitHub issues.

The Google Play Developer Reporting API exposes all of that — clusters, sample stack traces, user counts, error rates, per-device breakdowns. gplay wraps it as CLI commands.

The commands

# Crash clusters, last 7 days, top 20 by user impact
gplay vitals crashes query \
  --package com.example.app \
  --time-range LAST_7_DAYS \
  --page-size 20 \
  --paginate

# Full crash report for a specific cluster
gplay vitals crashes report \
  --package com.example.app \
  --cluster-name "crashes/abc123"

# ANR clusters
gplay vitals errors query \
  --package com.example.app \
  --issue-types APPLICATION_NOT_RESPONDING \
  --time-range LAST_7_DAYS

# Performance metrics (startup, rendering, battery)
gplay vitals performance startup \
  --package com.example.app \
  --time-range LAST_7_DAYS

Every command returns minified JSON by default. Add --output table if you’re eyeballing in a shell.

A ten-line CI regression gate

Drop this into a GitHub Actions job that runs an hour after promoting to production:

- name: Fail on crash regression
  env:
    GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
    GPLAY_PACKAGE: com.example.app
  run: |
    THIS_WEEK=$(gplay vitals crashes query --time-range LAST_7_DAYS \
      | jq '[.clusters[].distinctUsers // 0] | add')
    LAST_WEEK=$(gplay vitals crashes query --time-range PREVIOUS_7_DAYS \
      | jq '[.clusters[].distinctUsers // 0] | add')
    if [ "$THIS_WEEK" -gt $(( LAST_WEEK * 130 / 100 )) ]; then
      echo "Crash-affected users up >30% week over week ($LAST_WEEK -> $THIS_WEEK)"
      exit 1
    fi

That’s it. No third-party observability integration, no Play Console screen-scraping, no waiting for a human to notice.

Slack alerts for new crash clusters

Combine vitals crashes query with gplay notify send:

#!/usr/bin/env bash
# alert-new-crashes.sh — run hourly from cron
set -euo pipefail

NEW_CLUSTERS=$(gplay vitals crashes query \
  --package com.example.app \
  --time-range LAST_24_HOURS \
  --output json \
  | jq -c '[.clusters[] | select(.distinctUsers > 500)]')

COUNT=$(echo "$NEW_CLUSTERS" | jq 'length')
if [ "$COUNT" -eq 0 ]; then exit 0; fi

MSG=$(echo "$NEW_CLUSTERS" | jq -r 'map("- \(.name): \(.distinctUsers) users") | join("\n")')

gplay notify send \
  --webhook "$SLACK_WEBHOOK" \
  --message "🚨 $COUNT new high-impact crash clusters in the last 24h:\n$MSG"

Fastlane and gradle-play-publisher have nothing here. This is entirely Play Console territory, and it’s the kind of workflow that never gets built when it has to live in a web UI.

AI agent triage

Give your AI agent (Claude Code, Cursor, OpenClaw, Hermes Agent, or any of the 12 supported agents) this prompt:

Grab the top 10 crash clusters from the last week for com.example.app. For any cluster over 500 users where the top stack frame is in our own code (not Android framework), pull the full report and file a GitHub issue with the stack trace, user count, and affected devices. Skip clusters that already have an open issue.

Claude Code will chain gplay vitals crashes query → gplay vitals crashes report → gh issue list → gh issue create. Read the output, approve the writes, done.

Time ranges you can pass

gplay vitals commands accept the same time-range values as the Reporting API:

LAST_24_HOURS
LAST_7_DAYS
LAST_30_DAYS
PREVIOUS_7_DAYS (week-over-week comparisons)
PREVIOUS_30_DAYS
Custom ranges via --start-time and --end-time (RFC 3339 timestamps).

Filtering

Every vitals query accepts filter flags for OS version, device model, app version, and country:

gplay vitals crashes query \
  --package com.example.app \
  --time-range LAST_7_DAYS \
  --os-versions 34,33 \
  --app-versions 4.2.1 \
  --paginate

That’s how you isolate a regression to a specific Android version or hardware model, from the terminal, in seconds.

Performance vitals

Beyond crashes and ANRs, gplay vitals performance covers:

Startup latency — cold and warm start, per device class
Slow rendering — frozen frames, 16 ms budget breaches
Battery drain — background power usage, wakelocks
Excessive wakeups

Same JSON-first output, same filter surface, same CI-friendly ergonomics.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay vitals crashes query --package com.example.app --time-range LAST_7_DAYS --output table

Full vitals reference at /reference/vitals/. If you want a ready-made Slack alert setup, install the vitals monitoring skill and ask your AI agent to scaffold it against your webhook.

Pre-flight Google Play subscription validation: catch problems before Play rejects

Sun, 05 Jul 2026 00:00:00 GMT

Google Play subscription reviews have brutal feedback loops. Submit a new subscription with a missing German localization or an offer without an eligibility rule, and you’ll get a rejection notice hours or days later, with a “please fix and resubmit” wall of text that doesn’t quite tell you which field.

This is entirely avoidable. Every rejection reason maps to something you can check locally, in seconds, with gplay.

The checklist that gets you rejected

From reviewing hundreds of rejection cases, the recurring pattern:

Subscription created but never activated. status: PENDING — Google won’t display it.
Base plan created but no price set in one or more countries. Google won’t publish a base plan that’s missing prices in Play’s list of supported markets.
Free-trial offer with no eligibility rule. Google requires an eligibility rule (usually “new subscribers only”) or rejects the offer as promo-abuse-prone.
Offer name not localized for locales where the app is listed. Google flags this even for locales where you’d say “who cares, they read English fine.”
Introductory-price offer where the intro period equals the full billing period. Fails Google’s promo-value check.
Auto-renewing base plan without any offer (fine) alongside a legacy prepaid offer of the same product (not fine).
Product ID contains a character Google doesn’t accept in the current API version (mostly caught, but happens).
Subscription referenced by a paywall on your site that doesn’t exist. Not technically rejected by Play but breaks store link discoverability.

You want to catch every one of these before the submit button.

The command

gplay subscriptions validate \
  --package com.example.app \
  --product-id pro

Runs every check above against the current state in Play Console and prints a report:

Validating subscription 'pro' for com.example.app...

✓ Subscription status: ACTIVE
✓ 2 base plans: monthly (P1M), yearly (P1Y)

Base plan: monthly
  ✓ Auto-renewing
  ✓ Billing period valid: P1M
  ✓ Prices set in 175 regions
  ⚠ Price missing in 2 regions: TR, AR
  ✓ 1 offer: monthly-trial-7d

    Offer: monthly-trial-7d
      ✓ Phases valid: FREE_TRIAL P7D 0
      ✗ Eligibility rule missing — Google requires this for FREE_TRIAL offers
      ⚠ Offer name localized in 8/12 supported locales
        Missing: es-419, pt-BR, ja-JP, ko

Base plan: yearly
  ✓ Auto-renewing
  ✓ Billing period valid: P1Y
  ✓ Prices set in 175 regions
  ✓ No offers

Summary: 2 errors, 3 warnings.
Would likely be rejected on submission.

Fix the errors (missing eligibility rule, missing prices), address the warnings, re-run. Repeat until it says “OK to submit.”

What `--strict` adds

By default validate runs the required checks (things Google definitely rejects). Add --strict to also flag ergonomics issues that don’t necessarily fail review but hurt conversion:

gplay subscriptions validate --strict \
  --package com.example.app \
  --product-id pro

--strict adds:

Offer names shorter than 15 characters (“Trial” instead of “Try free for 7 days”).
Base plans with no renewal_type set (defaults to auto-renewing but explicit is better).
Prices where the yearly is not at least 15% cheaper than 12x monthly (weird pricing signal).
Missing tag on offers (SPECIAL_INTRO, LEGACY_INTRO) that RevenueCat and other billing wrappers use.

Not blocking, but worth reviewing.

Batch validate every subscription

gplay subscriptions list --package com.example.app \
  | jq -r '.[].productId' \
  | xargs -I{} gplay subscriptions validate --package com.example.app --product-id {}

Prints a report per subscription. Use this before any batch price change or when auditing an app you inherited.

Pre-flight in CI

Fail the pipeline if any subscription has errors:

- name: Validate subscriptions before promoting
  env:
    GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
  run: |
    gplay subscriptions list --package com.example.app \
      | jq -r '.[].productId' \
      | while read PRODUCT; do
        RESULT=$(gplay subscriptions validate \
          --package com.example.app \
          --product-id "$PRODUCT" \
          --output json)
        ERRORS=$(echo "$RESULT" | jq '.errors | length')
        if [ "$ERRORS" -gt 0 ]; then
          echo "❌ $PRODUCT has $ERRORS errors:"
          echo "$RESULT" | jq -r '.errors[] | "  - \(.field): \(.message)"'
          exit 1
        fi
      done

Runs every time you’re about to promote a build, in seconds.

Fixing the common errors

Missing eligibility rule for a free trial:

gplay offers update \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --offer-id monthly-trial-7d \
  --eligibility DEVELOPER_ELIGIBILITY_NEW_SUBSCRIBERS_ONLY

Missing prices in specific regions:

gplay baseplans prices set \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --region TR \
  --price-micros 149000000     # ₺149

Or expand from an anchor:

gplay baseplans prices convert \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --from-region US \
  --only-missing

Missing offer name localizations:

gplay offers locales set \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --offer-id monthly-trial-7d \
  --locales es-419:"Prueba gratis 7 días",pt-BR:"7 dias grátis",ja-JP:"7日間無料",ko:"7일 무료"

Subscription still in PENDING:

gplay subscriptions activate --package com.example.app --product-id pro

AI-agent-driven fix loop

Give your agent the validate output and let it fix in a loop:

Run gplay subscriptions validate for every subscription on com.example.app. For each error, fix it. For each warning, ask me before touching. When everything’s green, print the final validate output.

Chains: subscriptions list → per-subscription validate → per-error remediation command → re-validate → summary.

Works with all 12 supported agents. The IAP setup skill teaches the fix mappings so agents don’t need to guess:

npx skills add tamtom/gplay-cli-skills

What `validate` does NOT check

To be honest about the tool’s limits:

Google’s discretionary review. Play reviewers occasionally reject on judgment calls (e.g. “your feature description doesn’t match the subscription value”). No local tool catches this.
Policy changes since the check was written. Google updates review policies quarterly-ish; validate ships known-good checks, not future ones.
Cross-store consistency. If your App Store subscription has different phases than your Play one, validate won’t flag it (that’s what RevenueCat MCP is for).

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay subscriptions validate --package com.example.app --product-id <your-sub-id>

Full subscription reference at /reference/subscriptions/, offers at /reference/offers/. Run it before every submission — it takes about a second and catches every rejection reason we’ve seen.

Read and edit Google Play Console app info from the terminal

Sun, 05 Jul 2026 00:00:00 GMT

The Play Console web UI is fine for browsing. It’s not great for scripting, comparing state across apps, or feeding your AI agent structured data. gplay exposes the same information as JSON from your terminal — usually one command per screen you’d have clicked through.

This is a cheat sheet of the commands you’ll use daily.

Basic app info

gplay apps list                                    # every app the service account can see
gplay apps get --package com.example.app           # one app's full details

For a quick scan use table output:

gplay apps list --output table

Listings (title, description, screenshots, graphics)

# All locales for an app
gplay listings list --package com.example.app --output table

# One locale, full detail
gplay listings get --package com.example.app --locale en-US

# Update a single field
gplay listings update \
  --package com.example.app \
  --locale en-US \
  --short-description "The best way to X"

Full localization workflow: Managing 80+ Google Play locales from the terminal.

Version and track state

# What's live where?
gplay tracks list --package com.example.app --output table

# One track's current release
gplay tracks get --package com.example.app --track production

# What's the version code / name of the latest bundle in a track?
gplay tracks get --package com.example.app --track production \
  | jq -r '.releases[0] | "\(.name) (\(.versionCodes[0]))"'

Uploaded bundles and APKs

# Every AAB uploaded
gplay bundles list --package com.example.app

# Every APK
gplay apks list --package com.example.app

Handy for finding older builds you can roll back to, or checking whether a specific version code made it up.

Subscriptions, base plans, offers

gplay subscriptions list --package com.example.app --output table
gplay subscriptions get --package com.example.app --product-id pro

gplay baseplans list --package com.example.app --subscription-id pro
gplay offers list --package com.example.app --subscription-id pro --base-plan-id monthly

gplay baseplans prices list \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --output table

The last one is the moment you realize a spreadsheet isn’t your friend anymore.

In-app products (one-time purchases)

gplay iap list --package com.example.app --output table
gplay iap get --package com.example.app --product-id premium_upgrade

Reviews

# Recent reviews
gplay reviews list --package com.example.app --output table

# Only 1-2 star reviews from the last 14 days that mention "login"
gplay reviews list \
  --package com.example.app \
  --filter "rating<=2 AND text CONTAINS 'login'" \
  --time-range LAST_14_DAYS

Yes, that filter syntax works. Great for triaging support-worthy issues without opening the web UI.

Testers (closed testing tracks)

gplay testers list --package com.example.app --track alpha
gplay testers add --package com.example.app --track alpha --email tester@example.com

In-app messaging: real-time developer notifications

gplay pubsub topic get --package com.example.app     # which Pub/Sub topic Play publishes to

Useful when you’re setting up server-side purchase acknowledgment against real-time notifications.

Reports (financial, statistics)

# List available financial reports (earnings, sales, taxes)
gplay reports financial list --package com.example.app

# Download last month's earnings CSV from GCS
gplay reports financial download \
  --package com.example.app \
  --report-type EARNINGS \
  --year 2026 --month 6 \
  --output ./reports/

Editing safely with edit sessions

Play Console API changes go through an edit session — a transactional workspace that either fully commits or gets thrown away. gplay wraps this:

# Start a session, save the ID
EDIT_ID=$(gplay edit begin --package com.example.app | jq -r '.id')

# Make multiple changes referencing $EDIT_ID
gplay listings update --edit-id $EDIT_ID --locale en-US --title "New Title"
gplay listings update --edit-id $EDIT_ID --locale fr-FR --title "Nouveau titre"

# Commit atomically
gplay edit commit --package com.example.app --edit-id $EDIT_ID

# Or throw everything away
gplay edit cancel --package com.example.app --edit-id $EDIT_ID

Most gplay commands manage the edit session for you internally — you only need to think about it when you want atomicity across multiple writes. If Claude Code or another AI agent is making a multi-step update, prompt it to use an explicit edit session and cancel-on-error.

Everything as JSON, by default

Every command above returns minified JSON if you don’t add --output. Perfect for jq, agent parsing, storing snapshots for diffing.

Table output (--output table) is human-readable. Markdown (--output markdown) is what you’d paste into a PR description.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay apps list --output table

Full reference at /reference/. Every command supports --help — that’s usually faster than searching docs.

Set up a Google Play subscription with RevenueCat and gplay CLI

Sun, 05 Jul 2026 00:00:00 GMT

If you’ve set up a Google Play subscription with RevenueCat before, you know the split: RevenueCat manages the cross-store abstraction (entitlements, offerings, paywalls, receipt verification), and you do the Play Console side by hand in a web UI — create the subscription product, create a base plan, create offers, click through 175 country prices, localize the offer names.

The Play Console side of that story is what gplay automates. Paired with the RevenueCat MCP server, the entire stack now lives in your terminal (or your AI agent’s).

What each tool owns

Cleanest way to think about it:

Layer	Tool	Owns
Google Play native	gplay CLI	Subscription, base plans, offers, PPP-converted country prices, offer localization, purchase verification against Google
Cross-store abstraction	RevenueCat MCP	Entitlements, offerings, packages, paywalls, customer view, revenue analytics
Your app SDK	RevenueCat SDK	Present offerings, hand off to Play Billing, sync customer info

gplay talks to Google directly. RevenueCat talks to gplay’s output (the Play product IDs). Your app talks to RevenueCat.

The end-to-end flow

Let’s launch a new “Pro” subscription with monthly and yearly base plans, a 7-day free trial offer on monthly, and prices in USD, EUR, GBP, JPY, INR, BRL.

1. Create the Google Play subscription with gplay

gplay subscriptions create \
  --package com.example.app \
  --product-id pro \
  --listing en-US:title="Pro",description="Unlimited access to Pro features"

2. Add base plans

gplay baseplans create \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --billing-period P1M \
  --auto-renewing

gplay baseplans create \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id yearly \
  --billing-period P1Y \
  --auto-renewing

3. Set prices in the anchor country + expand with PPP

# Set the anchor price (US, monthly)
gplay baseplans prices set \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --region US \
  --price-micros 9990000    # $9.99

# Expand to 175 countries using Google's purchasing-power-parity conversion
gplay baseplans prices convert \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --from-region US

Same two commands for yearly at $99.99.

convert uses Google’s PPP tables — a $9.99 US price becomes ₹499 in India, R$19.90 in Brazil, ¥1500 in Japan, etc. You can override individual countries after.

4. Add a 7-day free-trial offer on monthly

gplay offers create \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --offer-id monthly-trial-7d \
  --phases FREE_TRIAL,P7D,0

5. Activate and localize

gplay subscriptions activate \
  --package com.example.app \
  --product-id pro

# Localize offer names for major markets
gplay offers locales set \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --offer-id monthly-trial-7d \
  --locales en-US:"7-day free trial",fr-FR:"7 jours gratuits",de-DE:"7 Tage kostenlos",es-ES:"7 días gratis",ja-JP:"7日間無料"

That’s the Google Play side, done. Take a screenshot of the Play Console page as proof — the subscription, both base plans, the trial offer, and localized names are all there.

Now wire it up in RevenueCat.

6. Register the products in RevenueCat

Prompt your AI agent (Claude Code, Cursor, or any of the 12 supported agents):

Using the RevenueCat MCP, register the Google Play products for com.example.app:

Product pro:monthly (subscription pro, base plan monthly)

Product pro:yearly (subscription pro, base plan yearly)

Then create a “Pro” entitlement and attach both products to it.

Under the hood the agent will call the RevenueCat MCP tools: create-product-in-store, create-entitlement, attach-products-to-entitlement. All you did was describe the intent.

7. Create the offering and packages

Create an offering called “default” with two packages: “$rc_monthly” mapped to pro:monthly and “$rc_annual” mapped to pro:yearly. Attach both to the “Pro” entitlement.

The agent calls create-offering, create-packages, attach-products-to-package.

Your app’s Purchases.getOfferings() will now return this shape.

8. Generate a paywall

RevenueCat’s MCP includes an AI paywall generator:

Generate a paywall for the “default” offering with a “Try Pro free for 7 days” hero, feature list of “Unlimited exports, No ads, Priority support”, and a testimonial from an existing paywall on file. Render a screenshot when done.

The MCP calls create-paywall-ai → returns a task ID → agent polls get-paywall-ai-task → then render-paywall-screenshot when ready. You get back a PNG.

9. Verify a test purchase (both sides)

After a tester runs a sandbox purchase in your app:

# Play-side verification
gplay purchases subscriptionsv2 get \
  --package com.example.app \
  --token "$PURCHASE_TOKEN"

And in RevenueCat via the MCP:

Look up the RevenueCat customer for user ID test-user-42 and show me their subscriptions and entitlements.

The Play subscriptionState and the RC entitlement should match. If they don’t, gplay tells you exactly what Google’s servers see; RC tells you what its webhook processed. That’s how you triage sync issues.

Why this split makes sense

Three things you get from doing it this way:

One source of truth per layer. The Play product IDs live in Play Console (managed by gplay). The RC entitlement/offering/paywall live in RevenueCat (managed by MCP). No copy-paste between dashboards.

AI-agent-driven. Both surfaces are agent-native. A prompt like “add a yearly plan with 30% discount for existing monthly users” becomes: gplay creates the base plan, RC MCP creates the targeting rule, done.

Cross-store when you’re ready. Everything above works for App Store Connect too — same RC MCP calls, use the asc CLI for the App Store side.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto

Install the RevenueCat MCP in your AI agent per RevenueCat’s setup docs, and install the subscription skill for gplay so your agent knows the full Play-side workflow:

npx skills add tamtom/gplay-cli-skills

Full subscription reference at /reference/subscriptions/, base plans at /reference/baseplans/, offers at /reference/offers/.

Staged rollouts on Google Play with GitHub Actions

Sun, 05 Jul 2026 00:00:00 GMT

Staged rollouts are the safest way to ship an Android release: start at 1% of production, watch the crash rate, ramp to 10%, 20%, 50%, 100%. Doing it manually in the Play Console is tedious. Doing it in CI, gated on real vitals, is where you actually want to live.

This post walks through a complete GitHub Actions workflow using gplay that:

Uploads a signed AAB to the internal track.
Promotes to production at 1% rollout after a soak period.
Ramps to 20% if crashes stay clean.
Ramps to 100% if week-over-week crashes are within tolerance.
Halts the rollout automatically if crashes regress.

The workflow

Save this as .github/workflows/release.yml:

name: Release to Google Play

on:
  push:
    tags: ['v*']
  workflow_dispatch:

env:
  GPLAY_PACKAGE: com.example.app
  GPLAY_NO_UPDATE: 1

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install gplay
        run: |
          curl -sSL https://raw.githubusercontent.com/tamtom/play-console-cli/main/install.sh | bash
          echo "$HOME/.gplay/bin" >> $GITHUB_PATH

      - name: Write service-account key
        env:
          PLAY_SA_JSON: ${{ secrets.PLAY_SA_JSON }}
        run: |
          echo "$PLAY_SA_JSON" > $RUNNER_TEMP/play-sa.json
          echo "GPLAY_SERVICE_ACCOUNT=$RUNNER_TEMP/play-sa.json" >> $GITHUB_ENV

      - name: Build AAB
        run: ./gradlew bundleRelease

      - name: Upload to internal track
        run: |
          gplay release \
            --track internal \
            --bundle app/build/outputs/bundle/release/app-release.aab \
            --release-notes "en-US=$(git log -1 --pretty=%B)"

  soak:
    needs: release
    runs-on: ubuntu-latest
    steps:
      - name: Wait 24 hours in internal
        run: sleep 86400
      - name: Check internal crashes
        env:
          GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
        run: |
          CRASH_USERS=$(gplay vitals crashes query \
            --time-range LAST_24_HOURS \
            | jq '[.clusters[].distinctUsers // 0] | add')
          if [ "${CRASH_USERS:-0}" -gt 50 ]; then
            echo "Internal soak failed: $CRASH_USERS crash-affected users"
            exit 1
          fi

  promote-1pct:
    needs: soak
    runs-on: ubuntu-latest
    steps:
      - name: Promote to production at 1%
        env:
          GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
        run: |
          gplay tracks promote \
            --from internal \
            --to production \
            --rollout 0.01
      - name: Notify Slack
        run: |
          gplay notify send \
            --webhook "${{ secrets.SLACK_WEBHOOK }}" \
            --message "🟢 Production rollout started at 1% for ${{ github.ref_name }}"

  ramp-20pct:
    needs: promote-1pct
    runs-on: ubuntu-latest
    steps:
      - name: Soak at 1% for 24h
        run: sleep 86400
      - name: Gate on crash regression
        env:
          GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
        run: |
          THIS=$(gplay vitals crashes query --time-range LAST_24_HOURS \
            | jq '[.clusters[].distinctUsers // 0] | add')
          BASELINE=$(gplay vitals crashes query --time-range PREVIOUS_7_DAYS \
            | jq '[.clusters[].distinctUsers // 0] | add / 7')
          if [ "${THIS:-0}" -gt $(( ${BASELINE:-0} * 130 / 100 )) ]; then
            gplay tracks halt-rollout --track production
            gplay notify send --webhook "${{ secrets.SLACK_WEBHOOK }}" \
              --message "🚨 Rollout halted: crashes up >30% vs 7-day baseline"
            exit 1
          fi
      - name: Ramp to 20%
        env:
          GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
        run: |
          gplay tracks update-rollout --track production --rollout 0.20

  ramp-100pct:
    needs: ramp-20pct
    runs-on: ubuntu-latest
    steps:
      - name: Soak at 20% for 48h
        run: sleep 172800
      - name: Full rollout
        env:
          GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
        run: |
          gplay tracks update-rollout --track production --rollout 1.0
          gplay notify send --webhook "${{ secrets.SLACK_WEBHOOK }}" \
            --message "🎉 100% rolled out for ${{ github.ref_name }}"

What’s happening at each stage

release — builds the AAB with Gradle and uploads to the internal track. Because we don’t set --rollout, internal ships at 100% (the standard for tester tracks).

soak — 24-hour hold at internal. Fails the workflow if crash-affected users exceed 50 (a hard number appropriate for a small internal audience; tune to your scale).

promote-1pct — gplay tracks promote copies the internal release to production at 1% rollout. Note --rollout takes a fraction (0.01 = 1%), not a percentage.

ramp-20pct — 24-hour soak at 1%, then compare this-week crash-affected users against the previous 7-day average. If we’re 30% or more above baseline, gplay tracks halt-rollout freezes production and Slack gets pinged. Otherwise ramp to 20%.

ramp-100pct — 48-hour soak at 20%, then push to 100%.

Manual rollback

If something looks off between automated stages:

# Halt the current rollout (holds at current fraction)
gplay tracks halt-rollout --track production

# Resume when ready
gplay tracks resume-rollout --track production

# Full rollback: promote the previous production build back in
gplay tracks promote --from production --to production \
  --from-version-code 4210 --rollout 1.0

Adding release notes

The workflow above uses the latest commit message as the en-US release note. For multi-locale releases:

gplay release \
  --track production \
  --bundle app-release.aab \
  --release-notes-file release-notes.yaml

Where release-notes.yaml is:

en-US: "Bug fixes and improvements"
fr-FR: "Corrections de bugs et améliorations"
de-DE: "Fehlerbehebungen und Verbesserungen"
es-ES: "Correcciones de errores y mejoras"
ja-JP: "バグの修正と改善"

Or let your AI agent generate them from git history:

gplay release-notes generate --since v1.4.0 --output release-notes.yaml

Storing the service account safely

The PLAY_SA_JSON secret should contain the full contents of your service-account key file. If your org policy forbids storing JSON as a secret, use OIDC to fetch it from Google Secret Manager at job start — gplay reads whatever path GPLAY_SERVICE_ACCOUNT points to.

Never commit the JSON to the repo.

Why this ends up cleaner than a Fastlane pipeline

One binary, one install step. No Ruby, no bundler, no Fastfile.
JSON output — the vitals gating step is a jq one-liner, not a scraper.
Halted rollouts are first-class — halt-rollout / resume-rollout / update-rollout are separate commands with clean semantics.
Same tool for post-release monitoring. Same CLI runs the promotion, gates on vitals, and pings Slack. One dependency.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto

Full track reference at /reference/tracks/, vitals at /reference/vitals/. If you want a starter Actions workflow for your project, install the rollout-management skill and ask your AI agent to scaffold it against your app’s package name and typical release cadence.

Sync Google Play subscription prices with RevenueCat across 175 countries

Sun, 05 Jul 2026 00:00:00 GMT

Google Play supports subscription pricing in 175 countries. RevenueCat abstracts pricing across stores. Keeping the two in sync — the actual per-country prices on Google Play, the offering-level packages in RevenueCat — is the kind of task that traditionally means opening two dashboards and a spreadsheet.

gplay covers the Google Play side; the RevenueCat MCP covers the RevenueCat side. Together, an AI agent can keep them synchronized in one prompt.

The pricing model, briefly

On Google Play:

A base plan has a regional price for each country, denominated in that country’s currency, stored in micro-units (1 USD = 1,000,000 micros).
Google offers a PPP conversion — you set the anchor (e.g. US $9.99), Google proposes prices for every other region weighted by local purchasing power. You accept, override, or reject per country.
Prices can change over time; you have to explicitly re-set them.

In RevenueCat:

A package (e.g. $rc_monthly) points to a store product (e.g. pro:monthly on Google Play).
The price RevenueCat sees is whatever Google Play reports for that product in the user’s region — RC doesn’t set prices, it observes them.
RC’s equalize-subscription-prices tool normalizes prices between stores (iOS ↔ Android) so that a user seeing $9.99 on iOS also sees the equivalent $9.99 on Android after currency and store-fee adjustments.

The takeaway: gplay writes the ground truth on Google Play. RevenueCat aligns iOS to match.

Step 1 — set the anchor price on Google Play

gplay baseplans prices set \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --region US \
  --price-micros 9990000

That’s your US monthly price at $9.99.

Step 2 — expand to all 175 countries with PPP

gplay baseplans prices convert \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --from-region US

convert uses Google’s PPP tables. Your $9.99 US price becomes:

India: ₹499
Brazil: R$19.90
Japan: ¥1,500
Turkey: ₺149
Argentina: AR$4,999
Nigeria: ₦4,500
… 170 more.

You can review the whole set:

gplay baseplans prices list \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --output table

Override any single country:

gplay baseplans prices set \
  --package com.example.app \
  --subscription-id pro \
  --base-plan-id monthly \
  --region GB \
  --price-micros 7990000    # £7.99 flat, not the PPP-converted £8.53

Step 3 — sync RevenueCat prices to match

Once Google Play has the prices you want, tell RevenueCat to align iOS to match:

Prompt your AI agent (Claude Code, Cursor, or any of the 12 supported agents):

Using the RevenueCat MCP, equalize subscription prices for the “default” offering so the App Store side matches what’s now on Google Play. Show me the diff before executing.

Under the hood the agent calls RC MCP’s equalize-subscription-prices — it reads Play Store prices as the source of truth and adjusts App Store prices to match after fee-and-currency normalization.

Full round trip: gplay writes to Google Play → RC observes → RC MCP equalizes App Store.

Step 4 — audit for drift

Prices drift over time. Google changes its PPP tables (sometimes materially). Local currency swings. Store fee changes.

Weekly audit prompt:

Compare the current Google Play prices for com.example.app pro subscription against the anchor ($9.99 US monthly) using PPP tables from 3 months ago. Flag any country where the current price is more than 15% off the recomputed PPP.

The agent chains gplay baseplans prices list → PPP math against the anchor → diff report.

You can also cross-reference with RevenueCat’s revenue metrics:

For countries where the Play price is >15% below the PPP anchor, pull the last 30 days of RC revenue metrics. Are we leaving money on the table?

RC MCP get-revenue-metric filtered by region → agent computes revenue-per-user against the reduced-price cohort.

Step 5 — coordinated price change

When you decide to raise US monthly from $9.99 to $12.99, you want the change to propagate cleanly.

Prompt:

Change Google Play US monthly price for pro subscription to $12.99, propagate via PPP to all other regions except IN and BR (keep them at current), then equalize RevenueCat so iOS matches. Show the full diff — old vs new for every affected region and every affected RC package — before executing.

Chains:

gplay baseplans prices set --region US --price-micros 12990000 (dry-run)
gplay baseplans prices convert --from-region US --exclude IN,BR (dry-run)
gplay baseplans prices list → diff vs pre-state
You approve.
Steps 1-2 re-run for real.
RC MCP equalize-subscription-prices triggers iOS equalization.
RC MCP list-prices to confirm alignment.

A price change that used to be a ticket handed between finance, product, and the mobile team is now a prompt.

What Fastlane and gradle-play-publisher can’t do

Neither supports subscription pricing at all. This isn’t a gap — they were built for a different scope. But if you’re doing anything with subscriptions, they’re not part of the toolchain.

gplay covers the full monetization surface; combined with RC MCP, that surface stretches across both stores.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto

Set up the RevenueCat MCP in your agent. Install the PPP pricing skill so your agent knows the anchor-and-convert pattern by default:

npx skills add tamtom/gplay-cli-skills

Full base plan pricing reference at /reference/baseplans/. Try the audit prompt above against your live subscriptions — most teams find at least three countries out of sync on the first run.

Verify Google Play purchases server-side without the Java SDK

Sun, 05 Jul 2026 00:00:00 GMT

Server-side purchase verification on Google Play is one of those tasks where the official docs steer you toward a specific stack — pull in the Google API Java client, set up OAuth, wire up the AndroidPublisher service, hand-roll the request. If your backend is Node, Go, Python, Rust, or basically anything else, you’re either translating that boilerplate or reaching for a community wrapper.

There’s a shorter path: gplay validates receipts from a single command line. It’s the same Google Play Android Publisher API call, just without the ceremony.

The full flow, condensed

Say your Android app sent your server a purchaseToken and a productId after a one-time purchase or subscription. You need to confirm with Google that it’s real, not consumed, and not refunded.

gplay purchases subscriptionsv2 get \
  --package com.example.app \
  --token "$PURCHASE_TOKEN"

Output (minified JSON, one line — shown here formatted for reading):

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "regionCode": "US",
  "lineItems": [{
    "productId": "monthly_pro",
    "expiryTime": "2026-08-05T12:34:56Z",
    "autoRenewingPlan": { "autoRenewEnabled": true }
  }],
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "linkedPurchaseToken": ""
}

Your backend parses that JSON and decides whether to grant entitlements.

Node.js example

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const run = promisify(execFile);

export async function verifySubscription(packageName, token) {
  const { stdout } = await run('gplay', [
    'purchases', 'subscriptionsv2', 'get',
    '--package', packageName,
    '--token', token,
  ]);
  const purchase = JSON.parse(stdout);
  return {
    active: purchase.subscriptionState === 'SUBSCRIPTION_STATE_ACTIVE',
    productId: purchase.lineItems?.[0]?.productId,
    expiresAt: purchase.lineItems?.[0]?.expiryTime,
  };
}

No googleapis dependency. No OAuth token management. gplay handles the service-account auth internally from the file at GPLAY_SERVICE_ACCOUNT.

Go example

package purchases

import (
    "context"
    "encoding/json"
    "os/exec"
)

type Verified struct {
    Active    bool   `json:"active"`
    ProductID string `json:"productId"`
    ExpiresAt string `json:"expiresAt"`
}

type v2 struct {
    State     string `json:"subscriptionState"`
    LineItems []struct {
        ProductID  string `json:"productId"`
        ExpiryTime string `json:"expiryTime"`
    } `json:"lineItems"`
}

func Verify(ctx context.Context, pkg, token string) (Verified, error) {
    out, err := exec.CommandContext(ctx, "gplay",
        "purchases", "subscriptionsv2", "get",
        "--package", pkg, "--token", token,
    ).Output()
    if err != nil {
        return Verified{}, err
    }
    var p v2
    if err := json.Unmarshal(out, &p); err != nil {
        return Verified{}, err
    }
    v := Verified{Active: p.State == "SUBSCRIPTION_STATE_ACTIVE"}
    if len(p.LineItems) > 0 {
        v.ProductID = p.LineItems[0].ProductID
        v.ExpiresAt = p.LineItems[0].ExpiryTime
    }
    return v, nil
}

Python example

import json
import subprocess

def verify_subscription(package: str, token: str) -> dict:
    out = subprocess.check_output([
        "gplay", "purchases", "subscriptionsv2", "get",
        "--package", package, "--token", token,
    ])
    purchase = json.loads(out)
    return {
        "active": purchase["subscriptionState"] == "SUBSCRIPTION_STATE_ACTIVE",
        "product_id": purchase["lineItems"][0]["productId"] if purchase.get("lineItems") else None,
        "expires_at": purchase["lineItems"][0].get("expiryTime") if purchase.get("lineItems") else None,
    }

Same command, three languages, same shape.

One-time products

For consumables and non-consumables:

gplay purchases products get \
  --package com.example.app \
  --product-id premium_upgrade \
  --token "$PURCHASE_TOKEN"

You get back purchaseState (0 = purchased, 1 = canceled, 2 = pending), consumptionState, and orderId. Same JSON shape, same backend integration.

Acknowledging purchases

Google requires purchases to be acknowledged within 3 days or they’re auto-refunded. gplay handles both flavors:

# Subscriptions
gplay purchases subscriptions acknowledge \
  --package com.example.app \
  --subscription-id monthly_pro \
  --token "$PURCHASE_TOKEN"

# Consumable products
gplay purchases products consume \
  --package com.example.app \
  --product-id gems_pack_100 \
  --token "$PURCHASE_TOKEN"

Both are idempotent — safe to retry.

Voided purchases (refunds, chargebacks)

To sweep for refunds you missed:

gplay purchases voided list \
  --package com.example.app \
  --start-time 2026-07-01T00:00:00Z \
  --paginate

--paginate fetches every page automatically. Run it as an hourly cron and revoke entitlements when a purchaseToken shows up.

Deployment

In your backend service or container, put the service-account JSON at a known path and set:

export GPLAY_SERVICE_ACCOUNT=/secrets/play-sa.json
export GPLAY_PACKAGE=com.example.app       # optional default
export GPLAY_NO_UPDATE=1                    # disable the update check in prod
export GPLAY_TIMEOUT=30s                    # tighter timeout for API paths

That’s the whole setup. No OAuth flow, no refresh tokens, no client library.

Why this ends up simpler than the SDK path

Language-agnostic. Your backend team keeps its stack; the CLI is the shared interface.
Static binary. 12 MB, no runtime dependency, works in alpine, distroless, Lambda custom runtime, wherever.
Deterministic JSON. The output shape is stable — no library version drift.
--dry-run for tests. Sanity-check request payloads in staging without hitting Google.
Same tool for the rest of Play Console. The same CLI that verifies purchases also uploads builds, checks vitals, and downloads reports. One dependency, six APIs.

Get started

brew install tamtom/tap/gplay
gplay setup --auto
gplay purchases subscriptionsv2 get --package com.example.app --token TEST_TOKEN

Full purchase reference at /reference/purchases/. If you’re validating high volume, install the purchase-verification skill and your AI agent will scaffold the backend integration for you.

Your first 5 commands after gplay setup --auto

Sun, 05 Jul 2026 00:00:00 GMT

You just ran:

brew install tamtom/tap/gplay
gplay setup --auto

--auto installed gcloud if missing, enabled the Google Play Android Publisher API in a fresh GCP project, created a service account, downloaded its key, and (assuming you accepted its Play Console invite) hooked it into your developer account.

Now what? Here are the five commands to run before you do anything else. Together they prove auth works, show you your app’s current state, and set you up to automate the rest.

1. `gplay auth doctor` — sanity-check the setup

gplay auth doctor

Runs every check that could bite you later:

Does the service-account JSON parse?
Does its email have Play Console developer access?
Does the linked GCP project have the Android Publisher API enabled?
Do all the requested scopes work with the current key?

If everything’s green, you’re wired up. If not, --fix --confirm tries to auto-remediate:

gplay auth doctor --fix --confirm

2. `gplay apps list` — see what you can touch

gplay apps list --output table

Every app the service account has access to. If you expected an app to show up and it doesn’t, the service account isn’t invited to it yet — do that in Play Console → Users and Permissions.

For scripting, drop --output table — the JSON is what agents want.

3. `gplay tracks list` — where does each app live?

Pick the app you’re focused on:

gplay tracks list --package com.example.app --output table

Shows every track (internal, alpha, beta, production, custom closed-testing) with the version code and rollout fraction currently live in each.

This is the map you’ll return to every time you’re about to promote or roll back.

4. `gplay listings list` — what does the store look like right now?

gplay listings list --package com.example.app --output table

Every localized store listing — title, short description, full description length, whether screenshots and graphics are set. If your app supports 10 locales, all 10 rows are here.

To fetch a single locale’s full text:

gplay listings get --package com.example.app --locale en-US

5. `gplay vitals crashes query` — how healthy is the app?

gplay vitals crashes query \
  --package com.example.app \
  --time-range LAST_7_DAYS \
  --output table

Top crash clusters over the last 7 days. If you were about to promote a release, this tells you whether the current production build is healthy enough to build on.

Pair it with:

gplay vitals performance startup \
  --package com.example.app \
  --time-range LAST_7_DAYS

For startup latency baseline.

Bonus: the two flags to memorize

Once you know your way around, these two flags change everything:

--dry-run — every write command intercepts the HTTP request and logs it to stderr without executing. Safe preview:

gplay listings update --dry-run \
  --package com.example.app \
  --locale en-US \
  --short-description "New tagline"

--paginate — every list command auto-fetches all pages:

gplay reviews list --package com.example.app --paginate

Together they cover 90% of what you’ll do.

Bonus: hand it off to an AI agent

Now that auth works and you know your app’s shape, install the Agent Skills:

npx skills add tamtom/gplay-cli-skills

Then in Claude Code (or any of the 12 supported agents):

What can you tell me about com.example.app? Summarize current tracks, active locales, top crashes, and any subscriptions.

The agent chains the five commands above (plus gplay subscriptions list) and gives you a one-paragraph brief. First-day productivity.

What comes next

Depending on why you installed gplay:

Automating releases? Read How to release an Android app to Google Play from the terminal.
Migrating from Fastlane? Read Migrate from Fastlane supply to gplay in an afternoon.
Managing subscriptions? Read Set up a Google Play subscription with RevenueCat and gplay CLI.
Monitoring vitals in CI? Read Monitor Google Play crashes and ANRs from the terminal.

Full command reference at /reference/.

gplay vs Fastlane supply: which Google Play CLI in 2026?

Sat, 04 Jul 2026 00:00:00 GMT

Fastlane supply has been the default answer to “how do I publish to Google Play from the command line?” for a decade. It’s battle-tested and it works. But it was designed for one job — pushing builds and metadata — and the Play Console has grown far beyond that: subscriptions with base plans and offers, purchase verification, vitals, reviews, permission management, private app publishing.

Here’s an honest look at where each tool stands.

The short version

Both handle the classics well: AAB/APK upload, track assignment, staged rollouts, store listings, screenshots.
gplay goes further: full monetization stack, purchase verification, vitals, reviews, reports, user management, Managed Google Play.
Runtime footprint is the sleeper difference: Fastlane needs a Ruby environment; gplay is one static Go binary.

Feature comparison

Capability	gplay	Fastlane supply
Upload AAB/APK, tracks, rollouts	✅	✅
Store listings & screenshots	✅	✅
Subscriptions, base plans, offers	✅ Full	❌
In-app products & one-time purchases	✅	❌
Purchase verification & refunds	✅	❌
Vitals: crashes, ANRs, performance	✅	❌
Reviews: read + reply	✅	❌
Financial & statistics reports	✅	❌
Users & permission grants	✅	❌
Managed Google Play (private apps)	✅	❌
Output format	Minified JSON	Human-oriented logs
Runtime	Single Go binary	Ruby + gems

Where Fastlane still wins

Fairness matters:

Ecosystem breadth — Fastlane is a whole automation framework (screenshots via screengrab, iOS support, plugins). If you already run a Fastfile for both platforms, that inertia is real.
Maturity — a decade of production use and a huge community.

If all you do is supply an AAB once a sprint, Fastlane keeps doing that fine.

Where gplay pulls ahead

1. Everything after the upload

Modern Play operations are mostly not uploads. Checking crash clusters before expanding a rollout, replying to reviews, creating a promotional offer, verifying a purchase token server-side — with Fastlane these all mean opening the web console. With gplay:

gplay vitals crashes query --package com.example.app --from 2026-06-27 --to 2026-07-04
gplay reviews reply --package com.example.app --review-id <ID> --text "Fixed in 2.1!"
gplay purchases subscriptionsv2 get --package com.example.app --token <TOKEN>

2. Scriptable, JSON-first output

Every gplay command emits minified JSON, so it pipes into jq, scripts, and AI agents without parsing log text:

gplay tracks list --package com.example.app | jq '.tracks[].track'

3. Zero-runtime install

CI images and dev machines don’t need Ruby. Install is one line, and startup is instant:

brew install tamtom/tap/gplay

4. Built for AI agents

Explicit flags, --help everywhere, --dry-run on every write, no interactive prompts — plus ready-made Agent Skills so Claude Code or Cursor can run your whole release flow.

Migrating from Fastlane

Already have a Fastlane metadata/ directory? gplay imports it directly:

gplay migrate fastlane --package com.example.app --dir ./fastlane/metadata/android

Your existing translations, descriptions, and screenshots come along; nothing is lost.

Bottom line

If your Play workflow is “upload an AAB, sometimes update a listing,” either tool works — pick whichever fits your stack. The moment your workflow touches subscriptions, purchase verification, vitals, reviews, or agents/automation beyond the upload, gplay covers ground Fastlane simply doesn’t.