gplay-cli-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Play CLI usage

Google Play CLI使用指南

Use this skill when you need to run or design

gplay

commands for Google Play Console.

当你需要为Google Play Console运行或设计

gplay

命令时可使用本技能。

Command discovery

命令发现

Always use

--help

to discover commands and flags.

```
gplay --help
```
```
gplay tracks --help
```
```
gplay tracks list --help
```

始终使用

--help

来查找命令和参数：

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

Command	描述
`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二进制文件自更新

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

优先使用显式的长参数（例如
```
--package
```
、
```
--output
```
）。
无交互式提示；破坏性操作需要添加
```
--confirm
```
参数。
当用户需要获取所有分页内容时使用
```
--paginate
```
。
使用
```
--dry-run
```
预览变更而不实际执行（
```
release
```
、
```
migrate
```
等写命令支持该参数）。

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
```
).

默认输出为压缩的JSON。
仅在需要人类可读的输出时使用
```
--output table
```
或
```
--output markdown
```
。
```
--pretty
```
仅对JSON输出有效。
你可以设置
```
GPLAY_DEFAULT_OUTPUT
```
环境变量来修改默认输出格式（例如
```
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.

优先使用服务账号认证：

gplay auth login --service-account /path/to/sa.json

。

备选环境变量：
```
GPLAY_SERVICE_ACCOUNT
```
、
```
GPLAY_PACKAGE
```
。
```
GPLAY_PACKAGE
```
可设置默认的包名。

Timeouts

超时设置

```
GPLAY_TIMEOUT
```
/
```
GPLAY_TIMEOUT_SECONDS
```
control request timeouts.

GPLAY_UPLOAD_TIMEOUT

GPLAY_UPLOAD_TIMEOUT_SECONDS

control upload timeouts.

```
GPLAY_TIMEOUT
```
/
```
GPLAY_TIMEOUT_SECONDS
```
控制请求超时时间。

GPLAY_UPLOAD_TIMEOUT

GPLAY_UPLOAD_TIMEOUT_SECONDS

控制上传超时时间。

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

Variable	用途
`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` ）

Common patterns

常见使用场景

List with pagination

带分页的列表查询

bash

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

bash

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

Parse JSON output with jq

用jq解析JSON输出

bash

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

bash

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

Use profiles

使用配置文件

bash

gplay auth add-profile production --service-account /path/to/prod-sa.json
gplay auth use-profile production
gplay --profile production tracks list --package com.example.app

bash

gplay auth add-profile production --service-account /path/to/prod-sa.json
gplay auth use-profile production
gplay --profile production tracks list --package com.example.app

Debug mode

调试模式

bash

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

bash

GPLAY_DEBUG=1 gplay tracks list --package com.example.app
GPLAY_DEBUG=api gplay tracks list --package com.example.app  # 查看HTTP详情

Dry run (preview changes)

试运行（预览变更）

bash

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

bash

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

初始化项目

bash

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

bash

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

List apps in developer account

列出开发者账号下的应用

bash

gplay apps list --developer-id 1234567890
gplay apps list --developer-id 1234567890 --output table

bash

gplay apps list --developer-id 1234567890
gplay apps list --developer-id 1234567890 --output table

Generate CLI documentation

生成CLI文档

bash

gplay docs generate --format markdown --output-dir ./docs

bash

gplay docs generate --format markdown --output-dir ./docs

Self-update

自更新

bash

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

bash

gplay update
gplay update --check  # 仅检查更新不安装

Financial reports

财务报表

bash

gplay reports financial list --developer <id>
gplay reports financial list --developer <id> --type earnings --from 2026-01 --to 2026-06
gplay reports financial download --developer <id> --from 2026-01 --type earnings --dir ./reports

bash

gplay reports financial list --developer <id>
gplay reports financial list --developer <id> --type earnings --from 2026-01 --to 2026-06
gplay reports financial download --developer <id> --from 2026-01 --type earnings --dir ./reports

Statistics reports

统计报表

bash

gplay reports stats list --developer <id>
gplay reports stats list --developer <id> --package com.example.app --type installs
gplay reports stats download --developer <id> --package com.example.app --from 2026-01 --type installs --dir ./reports

bash

gplay reports stats list --developer <id>
gplay reports stats list --developer <id> --package com.example.app --type installs
gplay reports stats download --developer <id> --package com.example.app --from 2026-01 --type installs --dir ./reports

Send notifications

发送通知

bash

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

bash

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

Edit sessions

编辑会话

Most write operations require an edit session:

bash

undefined

大部分写操作都需要编辑会话：

bash

undefined

Create edit

创建编辑会话

gplay edits create --package com.example.app

Returns: edit_id

返回：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>

undefined

gplay edits commit --package com.example.app --edit <edit_id>

undefined

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.

高层命令：
```
gplay release
```
（自动创建编辑会话、上传资源、提交变更）

手动命令：

gplay edits create

→

gplay bundles upload

→

gplay edits commit

追求简便请使用高层命令，需要细粒度控制请使用手动命令。