Gplay CLI Usage

gplay CLI conventions (foundation)

This is the foundation skill: the conventions that hold for every gplay command, factored out once so the workflow skills (see the Map of skills table at the end) can reference it instead of repeating them. The normative source of truth is docs/DESIGN.md in the CLI repo; this skill summarizes it for agents and does not freeze per-command flag lists.

--help is the source of truth

gplay's commands are self-describing. Confirm the current verbs, flags, and defaults from the binary, never from memory:

gplay --help                       # the whole command tree
gplay <group> --help               # a namespace (releases, tracks, team, …)
gplay <group> <command> --help     # one command, with its real flags
gplay exit-codes                   # the semantic exit-code table + diagnostic codes

If this skill and --help ever disagree, trust --help.

Stability: the [experimental] banner

gplay is GA since v1.0.0. A command whose --help opens with no [experimental] banner is covered by the Public contract: its name, flags, semantics and exit codes hold until a major bump, so CI can pin v1.

The banner marks the exceptions, per command; those surfaces sit outside the contract and can change in any release, so CI that depends on one pins an exact version (stability).

gplay schema: the offline API map

Where --help documents gplay's own surface, gplay schema introspects the underlying Android Publisher API offline (no credential, no HTTP call) from an index compiled into the binary: does a method exist, what does it send and return, what fields and enums does a type carry:

gplay schema --list                 # compact catalog: id · http · path
gplay schema tracks                 # match across method id, REST path, type name
gplay schema Track                  # expand a schema's fields, types, enums
gplay schema edits.tracks.update    # a method's request/response, one hop deep
gplay schema --method PATCH         # filter the method surface by HTTP verb
gplay schema --codes                # gplay's own diagnostic-code catalog (see Exit codes)

[experimental]: confirm the surface with gplay schema --help.

Which credential / account (resolution order)

Every authenticated command resolves the service-account credential in this order, highest priority first:

1. --service-account <path-or-inline-json>, a JSON file path or inline JSON content. Overrides everything below.
2. --account <name>, a specific stored Account. Overrides env + the active Account.
3. GPLAY_SERVICE_ACCOUNT env var, a path or inline JSON.
4. The active stored Account (set up via gplay auth login).

Setting this up from scratch is the gplay-setup skill. Auth problems exit 10 (bad/again credential) or 11 (the service account is not invited on the app/account).

Which app (--package + project pinning)

Most commands need a target package. Resolution (ADR-0004):

1. --package com.example.app on the command, else
2. the package pinned in .gplay/config.json for the current repo.

Pin once with gplay init (or gplay apps init) so day-to-day commands need no --package. Managing the registry of packages is the gplay-apps skill.

Two surfaces address elsewhere: customapps and team key on the developer account (--developer-id), and appstore carries a second package, --store-package, the app store making the call, alongside the app it acts on.

Output: table on a TTY, JSON in a pipe

--output takes table, json, or markdown. Resolution, most explicit first: the --output flag, then $GPLAY_DEFAULT_OUTPUT, then auto (ADR-0005): a human table on a terminal, JSON when piped or in CI. The env var beats the CI heuristic too (it is a value someone typed, CI/TTY are guesses); an unknown value is a usage error (exit 2) naming the variable. For machine consumption, ask for --output json explicitly; read commands pass the API payload through (ADR-0003), and write commands return the request/diff body, so a CI gate is usually one jq line. The pass-through promise is about not reshaping the API, not that every --output json is an API echo: the offline reference commands that wrap no API call, team permissions and schema, synthesize their own (gplay-owned, documented) JSON instead.

stdout is data, stderr is logs. Parse stdout; warnings, progress, and -v/--verbose flow steps go to stderr and never pollute the JSON. (Example: reviews list prints its "last 7 days only" warning to stderr.)

Two stderr signals worth reading before trusting a listing:

• Truncation. When --limit cuts a list, gplay prints a warning: line on stderr; stdout is byte-for-byte what it would be without the warning. An agent that only parses stdout cannot tell "that's all" from "capped", so read stderr, or pass --limit 0 where the command allows it.
• Redaction. Credentials (PEM blocks, service-account secrets, Authorization headers, JWTs, Google tokens) are masked on stderr; stdout stays verbatim. Do not expect a secret to appear in a diagnostic line.

Every single-value flag is accepted once. A repeated flag (--account a --account b, and even -vv) fails with exit 2 before auth and before any HTTP call; only list-valued flags such as --check or --stars repeat. When building a command line incrementally, replace a flag, never append it twice.

Exit codes: branch on the number, not the text

gplay exit-codes prints the full table. The semantic codes:

Agents should treat 3 as "append the named flag and re-run", 4 as "the environment forbids this write; do not retry, change the deployment", 40/50 as "back off and retry", 2/10/11/20/30 as "fix the input, do not retry blindly", and 70 as "the check worked, act on its report". 70 is a gate result, not a failure: the command read everything it meant to read. When a check command could not read some target, the ordinary API or network code wins over 70, so a sweep with holes never returns a clean 0.

Diagnostic codes: discriminate failures that share an exit code

Under --output json a failure carries a stable, machine-readable envelope on stdout (ADR-0044; stderr keeps the human prose):

{"error":{"code":"EDIT_ALREADY_EXISTS","exitCode":60,"retryable":false,"message":"..."}}

code is SCREAMING_SNAKE and append-only; retryable is the bit to branch on. The value of the envelope is where one exit code hides several causes: 60 covers STATE_CONFLICT, EDIT_ALREADY_EXISTS (commit or discard the open Edit), EDIT_EXPIRED (begin a new Edit and replay) and RATE_LIMIT_EXCEEDED (the only retryable one). 30 splits into INVALID_ARGUMENT, NOT_FOUND and API_ERROR. gplay schema --codes prints the whole catalog offline (--output json for a machine).

Safety: --dry-run everywhere, --confirm for live writes

• --dry-run is available on write commands: it validates inputs and prints the payload/diff it would send, with no HTTP call (and usually no auth needed). Reach for it before any production-affecting write.
• --confirm gates the writes that reach real users or the live store, production releases, metadata apply, compliance datasafety set, and destructive local writes like auth logout. Omitting it fails with exit 3 and names the flag (in the JSON error envelope: requires: ["confirm"]). CI=true never auto-confirms.
• --grant-admin is the stronger gate for conferring admin in gplay-team.
• GPLAY_READONLY=1 (truthy = enforced) is the environment-level guard for agent deployments that must only read. Because the safety flags above are advisory, an agent holding the credential can pass them itself; set this in the environment and the kernel refuses every mutating command before credential resolution and before any network call, regardless of flags, while read commands and --dry-run previews keep working. Its refusal exits 4 (denied by environment policy), which, unlike 3, is not resolvable by adding a flag; the only fix is to change the environment.

When a write refuses for a missing flag, the message names it; that refusal is agent-resolvable (ADR-0017): re-run with the flag it asked for. The GPLAY_READONLY refusal (exit 4) is the deliberate exception: it is not agent-resolvable.

The Edit lifecycle: implicit by default, explicit when you batch

Google Play mutations run inside a transactional Edit (edits.insert → change → edits.commit). gplay offers two ways to drive it.

Implicit (the default). Each write command performs the whole three-step dance on its own: it opens its own Edit, makes the change, and commits, discarding the Edit automatically on failure. You do not manage Edit IDs by hand. --keep-edit-on-failure skips that auto-discard for debugging.

Explicit (gplay edits …, when several changes must land together). To batch multiple writes into one atomic commit, open an Edit yourself:

gplay edits begin            # opens an Edit, pins its id to .gplay/edit-<package>.json
gplay metadata apply …       # these writes detect the pin and reuse the open Edit
gplay releases upload … --release-notes-dir ./notes
gplay edits status           # local read (no auth/network): shows the open edit, or none
gplay edits commit           # publish everything at once, and clear the pin
# gplay edits discard        # …or abandon the whole batch, clearing the pin

While the pin exists, subsequent write commands reuse the open Edit instead of opening their own, so the changes commit together or not at all. In explicit mode there is no auto-commit and no auto-discard; the lifecycle is yours until you commit or discard. Notes: a project (gplay init) is required since the pin lives under .gplay/; opening a second Edit while one is pinned is refused (exit 60); if commit fails (e.g. a validation error) the Edit stays open and the pin remains, fix and re-run, or discard.

(A few surfaces sit outside the Edit model on purpose: compliance datasafety, device-tiers, recovery, orders, vitals, games, subscriptions, iap, appstore are direct writes/reads with no editId, so edits begin does not batch them; their skills call that out.)

Map of skills