Google Play CLI usage
Use this skill when you need to run or design gplay commands for Google Play Console.
Command discovery
- Always use
--helpto discover commands and flags.gplay --helpgplay tracks --helpgplay tracks list --help
Available commands
| Command | Description |
|---|---|
gplay auth | Authentication and profile management |
gplay apps | List and manage apps in the developer account |
gplay init | Initialize a project with default config |
gplay release | High-level release workflow |
gplay promote | Promote releases between tracks |
gplay rollout | Manage staged rollouts |
gplay tracks | Track management |
gplay bundles | Bundle (AAB) management |
gplay edits | Edit session management |
gplay listings | Store listing management |
gplay images | Screenshot and image management |
gplay sync | Metadata sync (import/export) |
gplay validate | Offline validation of metadata |
gplay vitals | App vitals monitoring (crashes, performance, errors) |
gplay users | User management for developer account |
gplay grants | App-level permission grants |
gplay reports | Financial and statistics reports (list/download from GCS) |
gplay docs generate | Generate CLI documentation |
gplay migrate | Migration tools (e.g., from Fastlane) |
gplay notify | Send notifications (e.g., Slack, webhook) |
gplay update | Self-update the CLI binary |
Flag conventions
- Use explicit long flags (e.g.,
--package,--output). - No interactive prompts; destructive operations require
--confirm. - Use
--paginatewhen the user wants all pages. - Use
--dry-runto preview changes without executing them (supported byrelease,migrate, and other write commands).
Output formats
- Default output is minified JSON.
- Use
--output tableor--output markdownonly for human-readable output. --prettyis only valid with JSON output.- Set
GPLAY_DEFAULT_OUTPUTenvironment variable to change the default output format (e.g.,GPLAY_DEFAULT_OUTPUT=table).
Authentication and defaults
- Prefer service account auth via
gplay auth login --service-account /path/to/sa.json. - Fallback env vars:
GPLAY_SERVICE_ACCOUNT,GPLAY_PACKAGE. GPLAY_PACKAGEcan provide a default package name.
Timeouts
GPLAY_TIMEOUT/GPLAY_TIMEOUT_SECONDScontrol request timeouts.GPLAY_UPLOAD_TIMEOUT/GPLAY_UPLOAD_TIMEOUT_SECONDScontrol upload timeouts.
Environment Variables
| Variable | Purpose |
|---|---|
GPLAY_SERVICE_ACCOUNT | Path to service account JSON |
GPLAY_PACKAGE | Default package name |
GPLAY_PROFILE | Active profile name |
GPLAY_TIMEOUT | Request timeout (e.g., 90s, 2m) |
GPLAY_TIMEOUT_SECONDS | Timeout in seconds (alternative) |
GPLAY_UPLOAD_TIMEOUT | Upload timeout (e.g., 5m, 10m) |
GPLAY_DEBUG | Enable debug logging (set to api for HTTP requests) |
GPLAY_NO_UPDATE | Disable update checks |
GPLAY_MAX_RETRIES | Max retries for failed requests (default: 3) |
GPLAY_RETRY_DELAY | Base delay between retries (default: 1s) |
GPLAY_DEFAULT_OUTPUT | Default output format (json, table, markdown) |
Common patterns
List with pagination
bashgplay tracks list --package com.example.app --paginate
Parse JSON output with jq
bashgplay tracks list --package com.example.app | jq '.tracks[] | select(.track == "production")'
Use profiles
bash# Create/login a named profile gplay auth login --profile production --service-account /path/to/prod-sa.json # Switch the active profile gplay auth switch --profile production gplay --profile production tracks list --package com.example.app
Debug mode
bashGPLAY_DEBUG=1 gplay tracks list --package com.example.app GPLAY_DEBUG=api gplay tracks list --package com.example.app # HTTP details
Dry run (preview changes)
bashgplay release --package com.example.app --track beta --bundle app.aab --dry-run gplay migrate fastlane --source ./fastlane/metadata/android --output-dir ./metadata --dry-run
Initialize a project
bashgplay init --package com.example.app --service-account /path/to/sa.json
List apps in developer account
bashgplay apps list gplay apps list --output table gplay apps list --paginate
Generate CLI documentation
bashgplay docs generate --output-file ./GPLAY.md gplay docs generate --output-file - # write to stdout
Self-update
bashgplay update gplay update --check # Check for updates without installing
Financial reports
bash# --bucket-id is the GCS bucket ID/URI from Play Console > Download reports > Copy Cloud Storage URI gplay reports financial list --bucket-id <id> gplay reports financial list --bucket-id <id> --type earnings --from 2026-01 --to 2026-06 gplay reports financial download --bucket-id <id> --from 2026-01 --type earnings --dir ./reports
Statistics reports
bashgplay reports stats list --bucket-id <id> gplay reports stats list --bucket-id <id> --package com.example.app --type installs gplay reports stats download --bucket-id <id> --package com.example.app --from 2026-01 --type installs --dir ./reports
Send notifications
bashgplay notify send --webhook-url https://hooks.slack.com/... --message "Release deployed"
Edit sessions
Most write operations require an edit session:
bash# Create edit gplay edits create --package com.example.app # Returns: edit_id # Make changes gplay bundles upload --package com.example.app --edit <edit_id> --file app.aab # Commit changes (publishes) gplay edits commit --package com.example.app --edit <edit_id>
High-level vs manual commands
- High-level:
gplay release(creates edit, uploads, commits) - Manual:
gplay edits create→gplay bundles upload→gplay edits commit
Use high-level for simplicity, manual for fine-grained control.
