play-console-cli

# gplay

> A fast, lightweight CLI for Google Play Console, built in Go. Designed for CI/CD pipelines and AI agents.

## Install

- Homebrew: `brew install tamtom/tap/gplay`
- Script: `curl -fsSL https://raw.githubusercontent.com/tamtom/play-console-cli/main/install.sh | bash`
- Self-update: `gplay update`

## Authentication

- Requires a Google Cloud service account with Play Console access
- `gplay auth setup --auto --project <gcp-project>` — automated setup: creates the service account, enables the API, downloads the key, and wires the profile (wraps gcloud); `--dry-run` previews steps
- `gplay auth login --service-account /path/to/key.json` — manual alternative
- `gplay auth doctor` validates credentials and permissions (`--fix --confirm` auto-fixes)
- `gplay doctor` runs 16 environment health checks (config, SA, DNS, disk, clock, audit, timeouts, etc.)
- Environment variable: `GPLAY_SERVICE_ACCOUNT=/path/to/key.json`

## Usage Patterns

- JSON-first: minified JSON output by default (token-efficient for agents)
- `--output table` or `--output markdown` for human-readable output
- `--paginate` fetches all pages automatically
- `--dry-run` intercepts write HTTP methods and logs to stderr without executing
- `--package com.example.app` specifies the target app (or set `GPLAY_PACKAGE`)
- `--help` on any command to discover flags and subcommands

## Key Commands

- `gplay apps list` — list apps accessible by the service account
- `gplay tracks list` — list release tracks (production, beta, alpha, internal)
- `gplay tracks get` — get track details including releases and version codes
- `gplay tracks update` — promote or update a release on a track
- `gplay listings get` — get store listing metadata for a locale
- `gplay listings update` — update store listing (title, descriptions, etc.)
- `gplay listings locales` — list available locales with validation
- `gplay vitals crashes` — crash clusters and reports
- `gplay vitals errors` — ANR and error issues and reports
- `gplay vitals performance` — startup time, rendering, and battery metrics
- `gplay users list/create/update/delete` — manage developer account users
- `gplay grants create/update/delete` — manage per-app permission grants
- `gplay reports financial` — list and download financial reports from GCS
- `gplay reports stats` — list and download statistics reports from GCS
- `gplay notify send` — send webhook notifications (Slack, Discord, generic)
- `gplay migrate fastlane` — migrate metadata from Fastlane directory structure
- `gplay release-notes set` — set release notes (plain text auto-assigned to en-US)
- `gplay validate` — pre-submission validation checks
- `gplay preflight --file <app.aab>` — offline compliance scan, no API calls. Decodes AndroidManifest.xml (binary AXML for APKs, aapt2 protobuf for AABs) and runs nine scanners: `manifest`, `permissions`, `native_libs` (incl. 16 KB page alignment), `metadata` (with `--listings-dir`), `secrets`, `billing`, `privacy`, `policy`, `size`. Select with `--only`/`--skip`, gate CI with `--fail-on`, list with `--list-scanners`
- `gplay bundles analyze --file <app.aab>` — offline size breakdown per module/bucket, top largest files
- `gplay bundles compare --base <a.aab> --candidate <b.aab> --threshold 2M` — size regression gate
- `gplay audit list/search/clear/path` — local journal of every invocation at `~/.gplay/audit.log` (disable with `GPLAY_AUDIT=0`)
- `gplay quota status` — daily + per-minute Play API quota usage derived from audit log
- `gplay rtdn setup/status/decode` — Real-Time Developer Notifications: Pub/Sub topic + Play publisher role, IAM status, typed payload decoder
- `gplay vitals crashes anomalies` — detected deviations in crash/ANR/error/performance metrics
- `gplay init` — initialize project configuration
- `gplay docs generate` — generate markdown command reference

## Configuration

- Global config: `~/.gplay/config.yaml`
- Local config: `./.gplay/config.yaml` (takes precedence)
- Key env vars: `GPLAY_PACKAGE`, `GPLAY_TIMEOUT`, `GPLAY_DEBUG`, `GPLAY_MAX_RETRIES`

## Development

- See `AGENTS.md` for full contribution guide and project structure
- `make dev` runs format + lint + test + build
- `make test` runs the test suite
- TDD is required: start with a failing test, then implement

## Links

- Repository: https://github.com/tamtom/play-console-cli
- Google Play API: https://developers.google.com/android-publisher
- API Reference: https://developers.google.com/android-publisher/api-ref/rest