gplay-cli-usage

name	gplay-cli-usage
description	Guidance for using the Google Play Console CLI in this repo (flags, output formats, pagination, auth, and discovery). Use when asked to run or design gplay commands or interact with Google Play Console via the CLI.

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

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

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

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.