google-play-cli

module

v0.17.0 Latest Latest Go to latest Published: Jul 23, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/PollyGlot/google-play-cli

Links

Open Source Insights

README ¶

gplay

Every team shipping an Android app eventually hits the same wall: Fastlane supply drags a Ruby runtime into your CI image, output meant for humans, and generic exit codes that make retry logic guesswork. gplay is what you'd build today if you started fresh — one static binary, no runtime, JSON output that matches the Google Play Developer API verbatim, semantic exit codes, safe production defaults.

Two ways to drive it: the raw CLI (flags, scripts, CI) or agent skills that run it from natural-language prompts.

Public preview — pre-1.0. A broad surface is already implemented: auth, apps, releases, tracks, reviews, metadata, compliance (Data Safety), team, and closed-track testers. Breaking changes are still possible before v1.0. See docs/BACKLOG.md for what's out of scope and ADR-0010 for the versioning policy.

Why

Standalone Go binary. No Ruby, no Node, no Python — one file in your CI image.
Built for CI and agents. TTY-aware output (table by default, json in pipes), explicit flags, semantic exit codes for retry decisions.
API-faithful. --output json returns the raw Google Play Developer API response shape — no custom envelope to learn. The Google docs are the schema docs.
Safe by default on production. Uploading or promoting to the production track creates a draft release unless you explicitly --complete or --staged <fraction>. See ADR-0002.

Install

All install methods are live: go install, Homebrew, the install script, and pre-built binaries for Linux, macOS, and Windows on the releases page.

# go install
go install github.com/PollyGlot/google-play-cli/cmd/gplay@latest

# Homebrew
brew install PollyGlot/tap/gplay

# Install script
curl -fsSL https://gplay.sh/install | sh

The install script verifies the archive's SHA-256 against the release checksums.txt and fails closed — a missing, incomplete, or mismatched checksum aborts the install. Set GPLAY_INSTALL_NO_VERIFY=1 to bypass (prints a warning, greppable in CI). To add cosign and provenance checks on top, see Verify a release.

Agent skills

gplay is built to be driven by AI agents, not just typed by hand. Agent skills turn a natural-language prompt into the right gplay invocation, with the safety rails baked in:

"Promote the latest internal build of com.example.myapp to beta." → the gplay-release-flow skill runs gplay releases promote --from internal --to beta for you.

Install them in one step — the one gplay command that needs Node/npx:

gplay install-skills

That wraps the skills CLI (npx skills add PollyGlot/google-play-cli-skills --global --agent '*' --yes), installing every skill for every detected agent. No Node? Run that npx line yourself, or browse the skills by hand. (Driving the Play API itself stays Node-free — install-skills is a workstation convenience, never on the CI path.)

Skills live in a companion repo — PollyGlot/google-play-cli-skills. Each is a folder with a SKILL.md documenting its intent, the commands it runs, and the rails it enforces. The roster is fixed by ADR-0021: one skill per shipped namespace, plus a gplay-cli-usage foundation.

Skill	Drives
`gplay-cli-usage`	Cross-cutting conventions (foundation)
`gplay-setup`	Auth onboarding
`gplay-apps`	Apps registry + details
`gplay-release-flow`	upload / promote / rollout
`gplay-tracks`	Tracks + testers
`gplay-reviews`	reviews list / reply
`gplay-metadata-sync`	Listings + images
`gplay-compliance`	Data Safety
`gplay-team`	users / grants / permissions

gplay-vitals and gplay-subscription-management are gated until those CLI surfaces land (#49, #51).

Quick start

# Point gplay at a Google Cloud service account JSON.
gplay auth login --service-account ./service_account.json

# List configured accounts and see which one is active.
gplay auth list
gplay auth status

# Verify the SA actually has access to your app.
gplay auth doctor --package com.example.myapp

# Bootstrap a project-local config (cascading: project → user → defaults).
gplay init

Full command reference: gplay --help (or gplay <subcommand> --help).

The Fastlane-replacement surface

The CLI the skills above drive — all working today (public preview):

# Upload an AAB to the internal track, with localized release notes.
gplay releases upload app.aab \
  --package com.example.myapp \
  --track internal \
  --release-notes-dir ./whatsnew

# Promote the latest internal build to beta.
gplay releases promote --package com.example.myapp --from internal --to beta

# Stage a production rollout, then advance it.
gplay releases rollout --package com.example.myapp --track production --to 0.10

# Read the most recent reviews (API exposes the last 7 days only) and reply.
gplay reviews list --package com.example.myapp --stars 1-2
gplay reviews reply --review-id REVIEW_ID --reply "Thanks for the feedback!"

How it's set up

Documentation-first: decisions are pinned before code so contributors and agents converge.

CLAUDE.md — project context and agent working instructions (read order, conventions, build/test, PR gate).
CONTEXT.md — glossary of canonical terms (Edit, Account, Project, ...). Use them verbatim.
docs/DESIGN.md — CLI conventions across commands (auth precedence, exit codes, output format, verbosity, edit lifecycle).
docs/BACKLOG.md — explicitly out-of-scope features.
docs/CI_CD.md — how to wire gplay into a CI pipeline (GitHub Actions example).
docs/adr/ — Architecture Decision Records.

Verify a release

Confirm an artifact came from this repo's release pipeline (cosign + provenance).

Every release publishes a cosign signature over checksums.txt and a GitHub build-provenance attestation over each archive — two independent ways to confirm an artifact really came from this repo's release pipeline before you trust it in CI.

# 1. Build-provenance attestation (needs the GitHub CLI; no extra download).
#    Proves the archive was built by this repo's release workflow.
gh attestation verify gplay_<version>_<os>_<arch>.tar.gz \
  -R PollyGlot/google-play-cli

# 2. cosign signature over checksums.txt (needs cosign). The checksum file
#    transitively covers every archive it lists, so verify it, then check
#    your archive against it.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/PollyGlot/google-play-cli/\.github/workflows/release\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
shasum -a 256 -c <(grep " gplay_<version>_<os>_<arch>.tar.gz$" checksums.txt)

Download checksums.txt and checksums.txt.sigstore.json from the same release as the archive. The install script already checks the SHA-256 against checksums.txt and fails closed; these commands add provenance and signature verification on top.

Contributing

See CONTRIBUTING.md. TL;DR: open an issue first for anything bigger than a typo, branch from main, open a PR.

License

Not affiliated with Google

gplay is an independent open-source project. It uses the public Google Play Developer API and is not endorsed by, affiliated with, or sponsored by Google LLC. "Google Play" is a trademark of Google LLC.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
gplay command
commands
apps/accessiblecmd Package accessiblecmd implements `gplay apps accessible list`: the server-authoritative enumeration of the Apps the active credential can access, via the Play Developer Reporting `apps.search` method (#347, ADR-0039).	Package accessiblecmd implements `gplay apps accessible list`: the server-authoritative enumeration of the Apps the active credential can access, via the Play Developer Reporting `apps.search` method (#347, ADR-0039).
apps/addcmd Package addcmd implements `gplay apps add`: register one or more Android packages under the active Account, each with a cheap edits.insert+delete access probe (skippable via --no-verify) so typos and missing per-app permission grants are caught at registration time rather than weeks later in CI.	Package addcmd implements `gplay apps add`: register one or more Android packages under the active Account, each with a cheap edits.insert+delete access probe (skippable via --no-verify) so typos and missing per-app permission grants are caught at registration time rather than weeks later in CI.
apps/detailscmd Package detailscmd implements `apps details`, a pure grouping noun over the App details resource — the app-global edits.details record holding defaultLanguage and the user-visible contact email/phone/website.	Package detailscmd implements `apps details`, a pure grouping noun over the App details resource — the app-global edits.details record holding defaultLanguage and the user-visible contact email/phone/website.
apps/initcmd Package initcmd implements `gplay init`: pin a package name to the current repo by writing .gplay/config.json (committed) and an adjacent .gplay/.gitignore.	Package initcmd implements `gplay init`: pin a package name to the current repo by writing .gplay/config.json (committed) and an adjacent .gplay/.gitignore.
apps/listcmd Package listcmd implements `gplay apps list`: print every Android package registered under the active Account, marking the one pinned by the current repo's .gplay/config.json.	Package listcmd implements `gplay apps list`: print every Android package registered under the active Account, marking the one pinned by the current repo's .gplay/config.json.
apps/removecmd Package removecmd implements `gplay apps remove`: drop an Android package from the active Account's local registry.	Package removecmd implements `gplay apps remove`: drop an Android package from the active Account's local registry.
apps/viewcmd Package viewcmd implements `gplay apps view`: a read-only sanity check on what the active service account sees for a given app.	Package viewcmd implements `gplay apps view`: a read-only sanity check on what the active service account sees for a given app.
auth/doctor Package doctor implements `gplay auth doctor`: ordered diagnostic checks (per docs/DESIGN.md §1) that catch credential misconfiguration before any other command tries to talk to the API.	Package doctor implements `gplay auth doctor`: ordered diagnostic checks (per docs/DESIGN.md §1) that catch credential misconfiguration before any other command tries to talk to the API.
auth/list Package list implements `gplay auth list`: print every registered Account with the active one marked.	Package list implements `gplay auth list`: print every registered Account with the active one marked.
auth/login Package login implements `gplay auth login`: register a service-account JSON as a named Account in the keystore and mark it active in the config.	Package login implements `gplay auth login`: register a service-account JSON as a named Account in the keystore and mark it active in the config.
auth/logout Package logout implements `gplay auth logout <name>`: remove a registered Account from both the config and the keystore.	Package logout implements `gplay auth logout <name>`: remove a registered Account from both the config and the keystore.
auth/status Package status implements `gplay auth status`: print which Account is active, the underlying client_email, the keystore backend in use, and (when applicable) the on-disk credential path.	Package status implements `gplay auth status`: print which Account is active, the underlying client_email, the keystore backend in use, and (when applicable) the on-disk credential path.
compliance/datasafety/set Package set implements `gplay compliance datasafety set`: it pushes the app's Data Safety declaration to Google from the canonical CSV.	Package set implements `gplay compliance datasafety set`: it pushes the app's Data Safety declaration to Google from the canonical CSV.
compliance/datasafety/validate Package validatecmd implements `gplay compliance datasafety validate`: an OFFLINE structural check of the canonical Data Safety CSV.	Package validatecmd implements `gplay compliance datasafety validate`: an OFFLINE structural check of the canonical Data Safety CSV.
customapps/create Package create implements `gplay customapps create`: create a private app distributed to one organisation through managed Google Play, via playcustomapp.accounts.customApps.create — the one Developer API path that creates an app record (ADR-0032).	Package create implements `gplay customapps create`: create a private app distributed to one organisation through managed Google Play, via playcustomapp.accounts.customApps.create — the one Developer API path that creates an app record (ADR-0032).
device-tiers/create Package create implements `gplay device-tiers create`: create a new (immutable) Device Tier Config on Play from a JSON DeviceTierConfig body read from --file or stdin.	Package create implements `gplay device-tiers create`: create a new (immutable) Device Tier Config on Play from a JSON DeviceTierConfig body read from --file or stdin.
device-tiers/devicetierscmd Package devicetierscmd holds the wiring shared by the three `gplay device-tiers` leaves (create/view/list): package resolution, the ADR-0018 shared table machinery, and 404/403 hint classification.	Package devicetierscmd holds the wiring shared by the three `gplay device-tiers` leaves (create/view/list): package resolution, the ADR-0018 shared table machinery, and 404/403 hint classification.
device-tiers/list Package list implements `gplay device-tiers list`: list the app's device tier configs (newest first).	Package list implements `gplay device-tiers list`: list the app's device tier configs (newest first).
device-tiers/view Package view implements `gplay device-tiers view <deviceTierConfigId>`: read a single device tier config by its server-assigned int64 id.	Package view implements `gplay device-tiers view <deviceTierConfigId>`: read a single device tier config by its server-assigned int64 id.
edits/begin Package begin implements `gplay edits begin`: open an explicit Edit on a package and persist its ID to .gplay/edit-<package>.json, so subsequent write commands in the same project reuse it instead of opening their own (the explicit Edit lifecycle, docs/DESIGN.md §4).	Package begin implements `gplay edits begin`: open an explicit Edit on a package and persist its ID to .gplay/edit-<package>.json, so subsequent write commands in the same project reuse it instead of opening their own (the explicit Edit lifecycle, docs/DESIGN.md §4).
edits/commit Package commit implements `gplay edits commit`: commit the explicit Edit pinned in .gplay/edit-<package>.json (edits.commit) and clear the pin on success.	Package commit implements `gplay edits commit`: commit the explicit Edit pinned in .gplay/edit-<package>.json (edits.commit) and clear the pin on success.
edits/discard Package discard implements `gplay edits discard`: discard the explicit Edit pinned in .gplay/edit-<package>.json (edits.delete) and clear the pin.	Package discard implements `gplay edits discard`: discard the explicit Edit pinned in .gplay/edit-<package>.json (edits.delete) and clear the pin.
edits/editscmd Package editscmd holds the wiring shared by the four `gplay edits` leaves (begin/commit/discard/status): package resolution, locating the project's .gplay/ pin directory, the operator-facing error shapes (CLI misuse → exit 2, no-open-Edit / already-open state → exit 60), and the small renderable the leaves return.	Package editscmd holds the wiring shared by the four `gplay edits` leaves (begin/commit/discard/status): package resolution, locating the project's .gplay/ pin directory, the operator-facing error shapes (CLI misuse → exit 2, no-open-Edit / already-open state → exit 60), and the small renderable the leaves return.
edits/status Package status implements `gplay edits status`: report the open explicit Edit pinned in .gplay/edit-<package>.json, or "no open explicit edit" when none is pinned.	Package status implements `gplay edits status`: report the open explicit Edit pinned in .gplay/edit-<package>.json, or "no open explicit edit" when none is pinned.
games/achievements/create Package create implements `gplay games achievements create --application-id <id>`: insert a new achievement configuration (achievementConfigurations.insert).	Package create implements `gplay games achievements create --application-id <id>`: insert a new achievement configuration (achievementConfigurations.insert).
games/achievements/delete Package delete implements `gplay games achievements delete <achievementId>`: delete an achievement configuration (achievementConfigurations.delete).	Package delete implements `gplay games achievements delete <achievementId>`: delete an achievement configuration (achievementConfigurations.delete).
games/achievements/list Package list implements `gplay games achievements list --application-id <id>`: list a game's achievement configurations (achievementConfigurations.list).	Package list implements `gplay games achievements list --application-id <id>`: list a game's achievement configurations (achievementConfigurations.list).
games/achievements/update Package update implements `gplay games achievements update <achievementId>`: replace an achievement configuration's metadata (achievementConfigurations.update, PUT).	Package update implements `gplay games achievements update <achievementId>`: replace an achievement configuration's metadata (achievementConfigurations.update, PUT).
games/achievements/view Package view implements `gplay games achievements view <achievementId>`: read a single achievement configuration (achievementConfigurations.get).	Package view implements `gplay games achievements view <achievementId>`: read a single achievement configuration (achievementConfigurations.get).
games/gamescmd Package gamescmd holds the wiring shared by the ten `gplay games` leaves (achievements + leaderboards × list/view/create/update/delete): Play Games application-ID resolution, the destructive-tier --confirm gate, the ADR-0018 shared table machinery, request-body construction for the writes, and 404/403 hint classification.	Package gamescmd holds the wiring shared by the ten `gplay games` leaves (achievements + leaderboards × list/view/create/update/delete): Play Games application-ID resolution, the destructive-tier --confirm gate, the ADR-0018 shared table machinery, request-body construction for the writes, and 404/403 hint classification.
games/gamescmd/gamescmdtest Package gamescmdtest is the test-only seam shared by the `gplay games` leaf tests: a RoundTripper that fakes the OAuth2 /token exchange plus a RunContext wired with a throwaway service account, so each leaf test asserts addressing and pass-through without re-copying the auth dance (mirrors the harness the device-tiers leaf tests inline).	Package gamescmdtest is the test-only seam shared by the `gplay games` leaf tests: a RoundTripper that fakes the OAuth2 /token exchange plus a RunContext wired with a throwaway service account, so each leaf test asserts addressing and pass-through without re-copying the auth dance (mirrors the harness the device-tiers leaf tests inline).
games/leaderboards/create Package create implements `gplay games leaderboards create --application-id <id>`: insert a new leaderboard configuration (leaderboardConfigurations.insert).	Package create implements `gplay games leaderboards create --application-id <id>`: insert a new leaderboard configuration (leaderboardConfigurations.insert).
games/leaderboards/delete Package delete implements `gplay games leaderboards delete <leaderboardId>`: delete a leaderboard configuration (leaderboardConfigurations.delete).	Package delete implements `gplay games leaderboards delete <leaderboardId>`: delete a leaderboard configuration (leaderboardConfigurations.delete).
games/leaderboards/list Package list implements `gplay games leaderboards list --application-id <id>`: list a game's leaderboard configurations (leaderboardConfigurations.list).	Package list implements `gplay games leaderboards list --application-id <id>`: list a game's leaderboard configurations (leaderboardConfigurations.list).
games/leaderboards/update Package update implements `gplay games leaderboards update <leaderboardId>`: replace a leaderboard configuration's metadata (leaderboardConfigurations.update, PUT).	Package update implements `gplay games leaderboards update <leaderboardId>`: replace a leaderboard configuration's metadata (leaderboardConfigurations.update, PUT).
games/leaderboards/view Package view implements `gplay games leaderboards view <leaderboardId>`: read a single leaderboard configuration (leaderboardConfigurations.get).	Package view implements `gplay games leaderboards view <leaderboardId>`: read a single leaderboard configuration (leaderboardConfigurations.get).
help/exitcodes Package exitcodes registers `gplay exit-codes` (also reachable as `gplay help exit-codes`): a help topic that prints gplay's semantic exit-code taxonomy (docs/DESIGN.md §9).	Package exitcodes registers `gplay exit-codes` (also reachable as `gplay help exit-codes`): a help topic that prints gplay's semantic exit-code taxonomy (docs/DESIGN.md §9).