Gplay CLI Usage

Google Play CLI usage

Use this skill when you need to run or design gplay commands for Google Play Console.

Command discovery

• Always use --help to discover commands and flags.
  • gplay --help
  • gplay tracks --help
  • gplay tracks list --help

Available commands

Flag conventions

• Use explicit long flags (e.g., --package, --output).
• No interactive prompts; destructive operations require --confirm.
• Use --paginate when the user wants all pages.
• Use --dry-run to preview changes without executing them (supported by release, migrate, and other write commands).

Output formats

• Default output is minified JSON.
• Use --output table or --output markdown only for human-readable output.
• --pretty is only valid with JSON output.
• Set GPLAY_DEFAULT_OUTPUT environment 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_PACKAGE can provide a default package name.

Timeouts

• GPLAY_TIMEOUT / GPLAY_TIMEOUT_SECONDS control request timeouts.
• GPLAY_UPLOAD_TIMEOUT / GPLAY_UPLOAD_TIMEOUT_SECONDS control upload timeouts.

Environment Variables

Common patterns

List with pagination

gplay tracks list --package com.example.app --paginate

Parse JSON output with jq

gplay tracks list --package com.example.app | jq '.tracks[] | select(.track == "production")'

Use profiles

# 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

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

gplay 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

gplay init --package com.example.app --service-account /path/to/sa.json

List apps in developer account

gplay apps list
gplay apps list --output table
gplay apps list --paginate

Generate CLI documentation

gplay docs generate --output-file ./GPLAY.md
gplay docs generate --output-file -   # write to stdout

Self-update

gplay update
gplay update --check  # Check for updates without installing

Financial reports

# --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

gplay 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

gplay notify send --webhook-url https://hooks.slack.com/... --message "Release deployed"

Edit sessions

Most write operations require an edit session:

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