play-console-cli

README

gplay — Google Play Console CLI for AI Agents

gplay is a fast, single-binary CLI for Google Play Console, built for AI coding agents — Claude Code, Codex, Cursor, Gemini CLI — and for humans who script. Release Android apps, create subscriptions, in-app products, and one-time purchases, verify purchases server-side, and monitor crashes and reviews through documented Google APIs.

It replaces Play Console clicking for many day-to-day workflows. Most deployment tools only handle standard AAB uploads — gplay supports 250+ commands across 9 official Google APIs: Android Publisher, Play Developer Reporting, Checks, both Play Games admin APIs, Managed Google Play, Play Integrity, Android Developer ID Status, and Cloud Storage for reports. Initial public-app setup, first upload, ordinary Google-managed Play App Signing enrollment, and legal declarations still require a manual Play Console handoff. Enterprise self-hosted Cloud KMS signing is supported through its separate official API. Gplay does not use private Console endpoints or authenticated browser automation.

Table of Contents

• Quick Start
  • Install
  • Authentication
• Highlights
• Use it with your AI agent
• How gplay compares
• Documentation
• Contributing
• License

Quick Start

Install

# Homebrew (recommended)
brew tap tamtom/tap
brew install tamtom/tap/gplay

# Standalone binary — macOS/Linux
curl -fsSL https://raw.githubusercontent.com/tamtom/play-console-cli/main/install.sh | bash

# Standalone binary — Windows (PowerShell)
irm https://raw.githubusercontent.com/tamtom/play-console-cli/main/install.ps1 | iex

Update: gplay update self-updates in place. It also checks for new versions on startup (disable with GPLAY_NO_UPDATE=1).

After your first successful metadata push, edit commit, or release with gh installed, gplay prints an optional star suggestion to stderr. It never waits for input or stars automatically: agents must ask you first. Set GPLAY_NO_STAR_PROMPT=1 to suppress the suggestion. See configuration.

Authentication

gplay authenticates to Google Play with a service account.

One-command setup (recommended)

gplay setup --auto

That's it. This will:

• Install gcloud if needed (via Homebrew on macOS, or curl on Linux)
• Log you into Google Cloud
• Create a service account and download credentials
• Open Play Console for the one manual step (granting access)
• Configure everything automatically

Pass --project <id> if gcloud has no default project, --dry-run to preview the commands, or --no-browser for CI/agent runs. Then verify with gplay auth doctor.

Already have a service account key?

gplay auth login --service-account /path/to/service-account.json

Manual setup

Set up the service account by hand (full control)

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Note your project ID

Step 2: Enable the API

1. Go to APIs & Services > Library
2. Search for "Google Play Android Developer API"
3. Click Enable

Step 3: Create a Service Account

1. Go to IAM & Admin > Service Accounts
2. Click Create Service Account
3. Give it a name (e.g., "gplay-cli")
4. Click Create and Continue, then Done
5. Click on the created service account
6. Go to Keys > Add Key > Create new key > JSON
7. Save the downloaded JSON file securely

Step 4: Grant Access in Play Console

1. Go to Google Play Console
2. Go to Users and permissions > Invite new users
3. Enter the service account email (from the JSON file, looks like name@project.iam.gserviceaccount.com)
4. Set permissions (Admin or specific app access)
5. Click Invite user

Step 5: Login with gplay

gplay auth login --service-account /path/to/service-account.json

# Verify it works
gplay auth doctor

Profiles for multiple accounts and troubleshooting: docs/authentication.md

Once authenticated, you're ready to go:

# Ship a release in one command
gplay release --package com.example.app --track production --bundle app.aab --rollout 0.1

# Create a subscription with base plans and offers
gplay subscriptions create --package com.example.app --json @subscription.json

# Everything outputs minified JSON — built for agents and pipes
gplay reviews list --package com.example.app | jq '.reviews[0]'

Highlights

• Current official API coverage — the reviewed manifest tracks 218 methods across eight Play-specific discovery APIs, plus the two Cloud Storage methods needed for reports. All 145 current Android Publisher methods have a CLI path; specialized third-party-store and enterprise-KMS commands are explicitly scope-gated.
• Explicit safety boundary — gplay capabilities distinguishes official, manual, and unsupported workflows; gplay bootstrap plan prepares initial app setup without logging in, contacting Google, or changing an account.
• Agent-native discovery — gplay search ranks commands, examples, flags, and canonical intents locally; gplay schema embeds all 218 reviewed endpoints and 566 official request/response definitions with no credentials or network access.
• Resilient one-shot workflows — workflow steps support opt-in bounded retries and per-attempt timeouts, persist structured attempt diagnostics, fingerprint definitions, and refuse ambiguous or changed-definition resumes.
• Local weekly/daily insights — compare installs, uninstalls, crashes, ANRs, and store-listing conversion from official Google Play CSV exports; UTF-8/UTF-16 are supported and missing metrics remain explicitly unavailable.
• Managed Google Play — publish private (custom) apps to specific organizations with gplay custom-apps create, straight from the terminal.
• Complete releases & rollouts — upload, track assignment, staged rollout with pause/resume/percentage control, promote between tracks, release notes from git history.
• Store listings, screenshots & localization — manage listing text, images, and metadata across every locale; sync with a local directory or Fastlane.
• Full monetization stack — subscriptions, base plans, promotional offers, in-app products, one-time purchases, regional price conversion. Pairs with RevenueCat: create products in Play with gplay, import them into RevenueCat.
• Purchase verification — verify tokens, acknowledge purchases, refund orders, decode RTDN webhooks.
• Offline preflight — gplay preflight --file app.aab fully decodes AndroidManifest.xml (binary AXML for APKs, aapt2 protobuf for App Bundles) and runs nine scanners with no API calls and no credentials: manifest flags, restricted permissions, 64-bit and 16 KB page alignment, listing text and real screenshot dimensions, secrets, billing, privacy SDKs, target API floor, and size. Catches the rejections before you upload.
• App health — crash clusters, ANRs, performance vitals, review replies, financial & statistics reports.
• Integrity and verification — decode Android/PC Play Integrity tokens, safely gate Device Recall writes, and check Android Developer ID package/certificate registration.
• AI-agent native — minified JSON output, explicit flags, --help everywhere, --dry-run for every write, no interactive prompts, Agent Skills included.
• Lightweight, zero runtime to install — a single compiled Go binary with instant startup. No Node.js, no Python, no JVM, no Gradle project required.

Use it with your AI agent

Every command is discoverable via --help, outputs token-efficient JSON, and never blocks on a prompt — so agents can drive the whole Play workflow. Install the ready-made skills:

# Inspect the immutable, checksum-verified install plan (no network or writes)
gplay install-skills --preview

# Install the reviewed skill pack without npm/npx or executing repository code
gplay install-skills

The installer pins one reviewed Git commit and verifies every skill tree before an atomic install. Existing skills are never replaced unless --force is explicit.

Then ask your agent things like "release this AAB to internal", "create monthly + yearly subscriptions with a 7-day trial and convert prices for all regions", or "summarize this week's crash clusters". Full guide: docs/ai-agents.md

How gplay compares

Versus Fastlane supply and gradle-play-publisher (all three cover AAB/APK upload, tracks, rollouts, and listings equivalently):

Capability	gplay	Fastlane supply	gradle-play-publisher
Subscriptions, base plans, offers, one-time purchases	✅ Full	❌	⚠️ Basic (no base plans/offers)
Purchase verification, orders, refunds	✅	❌	❌
Vitals: crashes, ANRs, performance	✅	❌	❌
Reviews: read + reply	✅	❌	❌
Financial & statistics reports	✅	❌	❌
Users & permission grants	✅	❌	❌
Offline preflight (manifest decode, 16 KB alignment, secrets)	✅ 9 scanners	❌	❌
Managed Google Play (private/custom apps)	✅	❌	❌
Google Checks compliance gate	✅	❌	❌
AI-agent-friendly output	✅ JSON default	❌ Human logs	❌ Gradle logs
Runtime	Single Go binary	Ruby + gems	JVM + Gradle project

Documentation

Guide	What's inside
Command reference (GPLAY.md)	Every command and flag, auto-generated
Authentication	Service account setup, profiles, auth doctor
Releasing	Releases, rollouts, listings, testers, pre-submission checks, Fastlane interop
Monetization	Subscriptions, IAP, one-time purchases, pricing, purchase verification, RevenueCat
Monitoring & operations	Vitals, reviews, reports, users, notifications, diagnostics
AI agents	Agent setup, skills, example prompts
Configuration	Config file, env vars, output formats, shell completion
CI/CD	GitHub Actions, GitLab CI, release gates
Policy-safe automation	Official API boundary and manual Play Console handoffs
Official API audit	Versions, method inventory, gaps, and testing boundary
Contributing	Development setup, testing, PR guidelines

Contributing

Contributions welcome — see CONTRIBUTING.md. Quick local check: make dev (format + lint + test + build).

License

MIT — see LICENSE.

---

Built with Go and ffcli