google-play-cli

module

v0.6.0 Latest Latest Go to latest Published: Jun 11, 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.

Public preview — pre-1.0. A broad surface is already implemented: auth, apps, releases, tracks, reviews, metadata (listings + images), compliance (Data Safety), team (users + grants), and closed-track testers. This is an invitation to test and give feedback — breaking changes are still possible before v1.0, where per-command stability labels will mark what's frozen. See docs/BACKLOG.md for what's intentionally 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://raw.githubusercontent.com/PollyGlot/google-play-cli/main/install.sh | sh

The install script verifies the downloaded archive's SHA-256 against the release checksums.txt and fails closed: a missing checksums.txt, a checksum file with no entry for your platform's archive, or a mismatch all abort the install (so an adversary who can influence the download path cannot defeat verification by withholding the checksum). For air-gapped or mirrored installs where the checksum file is unreachable, set GPLAY_INSTALL_NO_VERIFY=1 to bypass — it prints a prominent warning and is greppable in your CI config. To independently verify a release with cosign or GitHub attestations, see Verify a release below.

Verify a release

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.

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

These all work 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.
AGENTS.md — instructions for AI agents working in this repo. Reads CLAUDE.md, CONTEXT.md, DESIGN.md before generating code.
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.

Agent skills

Agent skills that drive gplay from natural-language prompts live in a companion repo: PollyGlot/google-play-cli-skills. Each skill is a folder with a SKILL.md file that documents the intent, the gplay commands it runs, and the safety rails it enforces. The roster is fixed by ADR-0021: one skill per shipped namespace, plus a gplay-cli-usage foundation.

npx skills add PollyGlot/google-play-cli-skills

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).

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/addcmd Package addcmd implements `gplay apps add`: register an Android package under the active Account, 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 an Android package under the active Account, 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.
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).
metadata/apply Package apply implements `gplay metadata apply`: reconcile the local Metadata tree with the Listings live on Google Play.	Package apply implements `gplay metadata apply`: reconcile the local Metadata tree with the Listings live on Google Play.
metadata/images/apply Package imagesapply implements `gplay metadata images apply`: reconcile the local Store-image tree with the images live on Google Play.	Package imagesapply implements `gplay metadata images apply`: reconcile the local Store-image tree with the images live on Google Play.
metadata/images/list Package imageslist implements `gplay metadata images list`: a read-only summary of the Store images live on Google Play for a package — one row per non-empty slot (a (locale, imageType) pair), showing the image count and each image's content sha256.	Package imageslist implements `gplay metadata images list`: a read-only summary of the Store images live on Google Play for a package — one row per non-empty slot (a (locale, imageType) pair), showing the image count and each image's content sha256.
metadata/images/pull Package imagespull implements `gplay metadata images pull`: it rapatriates the Store images live on Google Play for a package into the local Metadata tree on disk, under each locale's images/ sub-directory, alongside the text Listing `.txt` files.	Package imagespull implements `gplay metadata images pull`: it rapatriates the Store images live on Google Play for a package into the local Metadata tree on disk, under each locale's images/ sub-directory, alongside the text Listing `.txt` files.
metadata/images/validate Package imagesvalidate implements `gplay metadata images validate`: an OFFLINE lint of the on-disk Store-image tree.	Package imagesvalidate implements `gplay metadata images validate`: an OFFLINE lint of the on-disk Store-image tree.
metadata/list Package list implements `gplay metadata list`: a read-only summary of the Store front Listings live on Google Play for a package — one row per locale, showing which managed fields each locale has and the character length of each.	Package list implements `gplay metadata list`: a read-only summary of the Store front Listings live on Google Play for a package — one row per locale, showing which managed fields each locale has and the character length of each.
metadata/pull Package pull implements `gplay metadata pull`: it rapatriates the Store front Listings live on Google Play for a package into the local Metadata tree on disk.	Package pull implements `gplay metadata pull`: it rapatriates the Store front Listings live on Google Play for a package into the local Metadata tree on disk.
metadata/validate Package validatecmd implements `gplay metadata validate`: an OFFLINE lint of the on-disk Metadata tree.	Package validatecmd implements `gplay metadata validate`: an OFFLINE lint of the on-disk Metadata tree.
releases/list Package list implements `gplay releases list`: a read-only listing of every release currently attached to a track (draft, inProgress, halted, completed).	Package list implements `gplay releases list`: a read-only listing of every release currently attached to a track (draft, inProgress, halted, completed).
releases/promote Package promote implements `gplay releases promote`: the CLI glue that parses --from/--to plus the status overrides (per ADR-0002), resolves --package, and hands a PromoteOpts payload to internal/releases/orchestrator.	Package promote implements `gplay releases promote`: the CLI glue that parses --from/--to plus the status overrides (per ADR-0002), resolves --package, and hands a PromoteOpts payload to internal/releases/orchestrator.
releases/rollout Package rollout implements the staged-rollout state machine as four sibling commands — `gplay releases rollout / halt / resume / complete`.	Package rollout implements the staged-rollout state machine as four sibling commands — `gplay releases rollout / halt / resume / complete`.
releases/trackhint Package trackhint maps the one operator-facing failure that `releases upload` and `releases promote` share when they target a custom closed track that has not been created yet — a tracks.update 404 — to an actionable error pointing at `gplay tracks create <name>`.	Package trackhint maps the one operator-facing failure that `releases upload` and `releases promote` share when they target a custom closed track that has not been created yet — a tracks.update 404 — to an actionable error pointing at `gplay tracks create <name>`.
releases/upload Package upload implements `gplay releases upload`: the CLI glue that resolves --package, parses the status flags (per ADR-0002), and hands an Opts payload to internal/releases/orchestrator.	Package upload implements `gplay releases upload`: the CLI glue that resolves --package, parses the status flags (per ADR-0002), and hands an Opts payload to internal/releases/orchestrator.
reviews/list Package list implements `gplay reviews list`: a read-only listing of the user reviews the Google Play API exposes for a package.	Package list implements `gplay reviews list`: a read-only listing of the user reviews the Google Play API exposes for a package.
reviews/reply Package reply implements `gplay reviews reply`: post developer responses to user reviews, one at a time (--review-id + --reply) or in bulk from a TSV stream (--batch <file>\|-).	Package reply implements `gplay reviews reply`: post developer responses to user reviews, one at a time (--review-id + --reply) or in bulk from a TSV stream (--batch <file>\|-).
reviews/reviewerr Package reviewerr maps the two operator-facing failures of the Reviews API — a service account lacking the "Reply to reviews" permission (403) and an unknown package (404) — to actionable, hinted errors.	Package reviewerr maps the two operator-facing failures of the Reviews API — a service account lacking the "Reply to reviews" permission (403) and an unknown package (404) — to actionable, hinted errors.
schema Package schema implements `gplay schema`: an OFFLINE, no-auth, `[experimental]` reference command that introspects the Android Publisher API surface from an embedded Schema index (ADR-0022).	Package schema implements `gplay schema`: an OFFLINE, no-auth, `[experimental]` reference command that introspects the Android Publisher API surface from an embedded Schema index (ADR-0022).
team/grants/list Package list implements `gplay team grants list`: list the per-app Grants across the Developer account's members.	Package list implements `gplay team grants list`: list the per-app Grants across the Developer account's members.
team/grants/remove Package remove implements `gplay team grants remove <email> --package <pkg>`: remove a member's access to one app via grants.delete, targeted by email+package path (no pre-read), WITHOUT removing them from the account.	Package remove implements `gplay team grants remove <email> --package <pkg>`: remove a member's access to one app via grants.delete, targeted by email+package path (no pre-read), WITHOUT removing them from the account.
team/grants/set Package set implements `gplay team grants set <email> --package <pkg>`: grant or adjust a member's per-app access via an UPSERT by read-then-decide (ADR-0007 instinct): read the member's current grants → grants.create if the app grant is absent, grants.patch if present.	Package set implements `gplay team grants set <email> --package <pkg>`: grant or adjust a member's per-app access via an UPSERT by read-then-decide (ADR-0007 instinct): read the member's current grants → grants.create if the app grant is absent, grants.patch if present.
team/permissions Package permissions implements `gplay team permissions`: an OFFLINE leaf (no API, no auth, zero network) that publishes gplay's permission vocabulary — the curated aliases (alias → account `_GLOBAL` enum → app enum → label → including-bundles) and the frozen role bundles.	Package permissions implements `gplay team permissions`: an OFFLINE leaf (no API, no auth, zero network) that publishes gplay's permission vocabulary — the curated aliases (alias → account `_GLOBAL` enum → app enum → label → including-bundles) and the frozen role bundles.
team/teamcmd Package teamcmd holds the helpers shared by every `gplay team` leaf command: today, resolving the Developer account id (ADR-0015 cascade) and the type-once persistence that makes it sticky.	Package teamcmd holds the helpers shared by every `gplay team` leaf command: today, resolving the Developer account id (ADR-0015 cascade) and the type-once persistence that makes it sticky.
team/users/add Package add implements `gplay team users add <email>`: invite a member with account-wide permissions via users.create.	Package add implements `gplay team users add <email>`: invite a member with account-wide permissions via users.create.