gplay-cli-usage

Google Play CLI 用法

在需要运行或设计用于 Google Play Console 的 gplay 命令时，请使用此技能。

命令发现

• 始终使用 --help 来发现命令和标志。
  • gplay --help
  • gplay tracks --help
  • gplay tracks list --help

可用命令

命令	说明
gplay auth	身份验证和配置文件管理
gplay apps	列出并管理开发者账号中的应用
gplay init	使用默认配置初始化项目
gplay release	高级发布工作流
gplay promote	在不同轨道之间提升版本
gplay rollout	管理分阶段发布
gplay tracks	轨道管理
gplay bundles	Bundle（AAB）管理
gplay edits	编辑会话管理
gplay listings	商店商品信息管理
gplay images	截图和图片管理
gplay sync	元数据同步（导入/导出）
gplay validate	离线验证元数据
gplay vitals	应用运行状况监控（崩溃、性能、错误）
gplay users	开发者账号的用户管理
gplay grants	应用级权限授予
gplay reports	财务和统计报告（从 GCS 列出/下载）
gplay docs generate	生成 CLI 文档
gplay migrate	迁移工具（例如，从 Fastlane 迁移）
gplay notify	发送通知（例如，Slack、webhook）
gplay update	自行更新 CLI 二进制文件

标志约定

• 使用明确的长标志（例如，--package、--output）。
• 不提供交互式提示；破坏性操作需要 --confirm。
• 用户需要所有页面时，请使用 --paginate。
• 使用 --dry-run 可预览更改而不执行（release、migrate 和其他写入命令支持此选项）。

输出格式

• 默认输出为精简 JSON。
• 仅在需要人类可读的输出时使用 --output table 或 --output markdown。
• --pretty 仅适用于 JSON 输出。
• 设置 GPLAY_DEFAULT_OUTPUT 环境变量可更改默认输出格式（例如，GPLAY_DEFAULT_OUTPUT=table）。

身份验证和默认值

• 优先使用服务账号身份验证：gplay auth login --service-account /path/to/sa.json。
• 备用环境变量：GPLAY_SERVICE_ACCOUNT、GPLAY_PACKAGE。
• GPLAY_PACKAGE 可提供默认包名。

超时

• GPLAY_TIMEOUT / GPLAY_TIMEOUT_SECONDS 控制请求超时。
• GPLAY_UPLOAD_TIMEOUT / GPLAY_UPLOAD_TIMEOUT_SECONDS 控制上传超时。

环境变量

变量	用途
GPLAY_SERVICE_ACCOUNT	服务账号 JSON 文件的路径
GPLAY_PACKAGE	默认包名
GPLAY_PROFILE	活动配置文件名称
GPLAY_TIMEOUT	请求超时（例如，90s、2m）
GPLAY_TIMEOUT_SECONDS	超时时间（秒），替代选项
GPLAY_UPLOAD_TIMEOUT	上传超时（例如，5m、10m）
GPLAY_DEBUG	启用调试日志（设为 api 可记录 HTTP 请求）
GPLAY_NO_UPDATE	禁用更新检查
GPLAY_MAX_RETRIES	失败请求的最大重试次数（默认值：3）
GPLAY_RETRY_DELAY	重试之间的基础延迟（默认值：1s）
GPLAY_DEFAULT_OUTPUT	默认输出格式（json、table、markdown）

常见模式

分页列出

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

使用 jq 解析 JSON 输出

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

使用配置文件

# 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

调试模式

GPLAY_DEBUG=1 gplay tracks list --package com.example.app
GPLAY_DEBUG=api gplay tracks list --package com.example.app  # HTTP details

试运行（预览更改）

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

初始化项目

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

列出开发者账号中的应用

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

生成 CLI 文档

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

自行更新

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

财务报告

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

统计报告

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

发送通知

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

编辑会话

大多数写入操作都需要编辑会话：

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

高层命令与手动命令

• 高层命令：gplay release（创建编辑、上传并提交）
• 手动命令：gplay edits create → gplay bundles upload → gplay edits commit

为简便起见，使用高层命令；如需精细控制，则使用手动命令。