gplay-cli-usage

已同步 v1.1.0 授權: MIT 來源: tamtom/gplay-cli-skills/skills/gplay-cli-usage 提交: 10301b2 收錄的最新變更:

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.

摘要

用途
gplay CLI 可用於處理 Google Play Console 工作，例如管理版本發布、應用程式中繼資料、權限與報表。
使用時機
可用它為列出、發布、驗證或查詢應用程式報表選擇命令、旗標、驗證方式與輸出設定。
輸出結果
命令預設輸出精簡 JSON，也可選擇表格或 Markdown；產生的文件與下載的報表可儲存為檔案。
上游變更（4 筆，最新收錄 2026-07-04）
439c9ae fix(skills): audit cleanup — correct every command, cut dead weight, add drift guardrail (#3) 範例現在使用 `auth login` 和 `switch` 管理設定檔、不帶 `--developer-id` 列出應用程式並可選擇輸出格式或分頁、以 `--output-file` 產生文件、使用 bucket ID 處理財務與統計報表，並以 `notify send --webhook-url` 發送通知。
d531a45 feat: add gplay-reports-download skill and update README 報表項目現在說明可從 GCS 列出或下載財務與統計報表，範例也改用各自的財務及統計列出／下載子命令。
f8592d5 feat: add skills for v0.4.2 new commands (vitals, users, migrate) 指南新增命令目錄與環境變數參考，說明 dry-run 和預設輸出行為，並加入初始化、列出應用程式、產生文件、自我更新、報表及通知的範例。
acb31df Initial commit: Google Play CLI Skills repository 初始變更新增 Google Play CLI 使用技能，涵蓋命令探索、旗標與輸出慣例、驗證與逾時、常用命令範例、編輯工作階段，以及高階與手動工作流程。
npx skills add "lettucebo/Skills#v2.2.0@gplay-cli-usage" --full-depth

⚠ v2.2.0 發布後即可使用

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.

歷程

v1.1.0 baseline-verified 10301b2
v1.1.0 license-refresh 10301b2