google-play-cli

module

v0.1.0-alpha.1 Latest Latest Go to latest Published: May 22, 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 — Google Play Developer CLI

A fast, lightweight, scriptable CLI for the Google Play Developer API. Replace Fastlane/Ruby on Android CI pipelines and enable autonomous app administration from your terminal, IDE, or AI agent.

Status: pre-1.0. The MVP surface is being implemented. Expect breaking changes. See docs/BACKLOG.md for what's intentionally out of scope today.

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

(Coming as soon as the first release ships. Channels planned for v0.1: GitHub Releases binaries, Homebrew tap, curl ... | sh install script, go install.)

# Homebrew (planned)
brew install PollyGlot/gplay/gplay

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

# go install (works once the repo has a tagged release)
go install github.com/PollyGlot/google-play-cli/cmd/gplay@latest

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

Planned for v0.1 stable

The Fastlane-replacement surface lands incrementally on the road to v0.1.0. These commands are not yet implemented in the current pre-release:

# Upload an AAB to the internal track.
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

# Read the most recent reviews (API exposes the last 7 days only).
gplay reviews list --package com.example.myapp --stars 1-2

See docs/BACKLOG.md for the full roadmap and what is intentionally out of scope.

How it's set up

The repo is documentation-first by design. Before writing significant code, the decisions are pinned in place so contributors and agents converge:

CLAUDE.md — project context and roadmap.
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.

Skills repo (planned)

Agent skills that drive gplay from natural-language prompts will 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.

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/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.
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.
internal
auth/doctor Package doctor runs ordered diagnostic checks against a resolved service-account credential and reports a structured result per check.	Package doctor runs ordered diagnostic checks against a resolved service-account credential and reports a structured result per check.
auth/keystore Package keystore stores service-account JSON credentials by name.	Package keystore stores service-account JSON credentials by name.
auth/resolver Package resolver picks the credential the next API call will use.	Package resolver picks the credential the next API call will use.
auth/serviceaccount Package serviceaccount loads and validates Google Cloud service-account JSON files.	Package serviceaccount loads and validates Google Cloud service-account JSON files.
auth/token Package token mints OAuth2 access tokens for the Google Play Developer API from a parsed service account.	Package token mints OAuth2 access tokens for the Google Play Developer API from a parsed service account.
config Package config owns gplay's cascading configuration model.	Package config owns gplay's cascading configuration model.
exit Package exit maps typed errors to the semantic exit codes documented in docs/DESIGN.md §9.	Package exit maps typed errors to the semantic exit codes documented in docs/DESIGN.md §9.
kernel Package kernel owns the per-invocation boot sequence shared by every gplay command: build the Boot once in cmd/gplay/main.go, the cobra layer captures the request-shaped Inputs, and kernel.Run resolves Account / Project / Format once before handing a populated RunContext to the command's business function.	Package kernel owns the per-invocation boot sequence shared by every gplay command: build the Boot once in cmd/gplay/main.go, the cobra layer captures the request-shaped Inputs, and kernel.Run resolves Account / Project / Format once before handing a populated RunContext to the command's business function.
output Package output owns Format selection and rendering dispatch for gplay commands.	Package output owns Format selection and rendering dispatch for gplay commands.
output/outputtest Package outputtest is the test-only seam for internal/output.	Package outputtest is the test-only seam for internal/output.
transport Package transport exposes the HTTP middleware gplay layers on top of the oauth2 client.	Package transport exposes the HTTP middleware gplay layers on top of the oauth2 client.
walkup Package walkup walks up from a starting directory looking for a file, mirroring git's `.git/` discovery.	Package walkup walks up from a starting directory looking for a file, mirroring git's `.git/` discovery.