蒲公英 CLI

一、工具介绍

@pgyer/cli 是蒲公英应用分发平台官方提供的命令行工具，支持：

应用上传（IPA / APK / HAP）
应用管理（查看 / 删除 / 详情）
账户认证与 API Token 管理

通过 CLI，开发者可以在本地、脚本或 CI/CD 环境中，快速完成应用发布流程，无需打开浏览器。

二、核心优势

相比传统网页操作，CLI 工具有几个明显优势：

✅ 自动化友好

支持 CI/CD（GitHub Actions / Jenkins / GitLab CI）
可嵌入脚本，实现自动发布

✅ AI / Agent 友好（重要）

CLI 原生支持结构化 JSON 输出，适合：

AI Agent 自动调用
LLM 工具链集成
自动化流程编排

✅ 双输出模式（独特设计）

根据运行环境自动切换：

人类友好（Human 模式）
程序友好（JSON 模式）

无需手动判断环境。

三、安装方式

使用 npm 全局安装

npm install -g @pgyer/cli

使用 npx（无需安装）

npx @pgyer/cli

环境要求

Node.js >= 18.0.0

四、快速开始

1️⃣ 登录账号

pgyer auth login

将自动打开浏览器完成授权。

2️⃣ 上传应用

pgyer upload ./app-release.apk

支持格式：

.apk
.ipa
.hap

3️⃣ 查看应用列表

pgyer apps list

五、输出模式说明（重点）

CLI 提供两种输出模式，适配不同使用场景。

自适应模式（默认）

工具会自动判断运行环境：

终端（TTY） → Human 模式（带颜色、表格）
脚本 / 管道 / CI → JSON 模式（结构化输出）

示例：

# 终端运行（人类可读）
pgyer apps list

# 管道运行（JSON）
pgyer apps list | jq '.apps[0].name'

Human 模式（`--human` / `-H`）

适合人工查看：

彩色输出
状态图标（✔ ✖ ℹ）
表格对齐
加载动画

pgyer apps list --human

JSON 模式（`--json`）

适合程序调用：

纯 JSON 输出
无颜色、无动画
错误输出到 stderr

pgyer apps list --json

优先级规则

--human > --json > 自动判断

六、认证方式

方式一：浏览器登录（推荐）

pgyer auth login

方式二：API Key（适合 CI）

export PGYER_API_KEY=your-api-key

无需登录即可使用 CLI。

查看登录状态

pgyer auth status

查看 API Token

pgyer auth token

退出登录

pgyer auth logout

七、应用管理命令

查看应用列表

pgyer apps list

查看应用详情

pgyer apps info <appKey>

删除应用

pgyer apps delete <appKey>

强制删除：

pgyer apps delete <appKey> --force

八、应用上传

基础用法

pgyer upload <file>

常用参数

参数	说明
`--app-key`	指定应用
`--build-update-description`	更新说明
`--password`	设置安装密码
`--invite-install`	邀请安装
`--pubstart`	开始日期
`--pubend`	结束日期
`--short`	短链接

示例

设置密码安装

pgyer upload app.apk --password 123456

设置有效期

pgyer upload app.ipa \
  --pubstart 2024-01-01 \
  --pubend 2024-12-31

添加更新说明

pgyer upload app.apk \
  --build-update-description "修复已知问题"

九、配置说明

优先级

CLI 参数 > 环境变量 > 配置文件

环境变量

变量	说明
`PGYER_API_KEY`	API Key
`PGYER_OUTPUT_FORMAT`	输出格式

配置文件

路径：

~/.config/pgyer/config.json

示例：

{
  "apiKey": "xxx",
  "apiUrl": "https://api.pgyer.com",
  "outputFormat": "json"
}

十、CI/CD 使用示例

npm install -g @pgyer/cli
export PGYER_API_KEY=your-api-key
pgyer upload ./app.apk

十一、最佳实践

✅ 使用 API Key 做自动化认证

避免在 CI 中使用登录流程。

✅ 强制使用 JSON 输出

pgyer upload app.apk --json

方便脚本解析。

✅ 与通知系统结合

上传完成后推送：

Telegram
Slack
Email

十二、适合 AI / 自动化的使用方式（亮点）

推荐在以下场景中使用 CLI：

AI 自动发布 App
自动构建 → 自动上传 → 自动通知
DevOps 自动化流程

CLI 的 JSON 输出非常适合：

? LLM / Agent 直接解析结果 ? 自动获取下载地址 / appKey ? 构建完整发布流水线

总结

蒲公英 CLI 的核心价值：

一行命令完成应用上传
支持自动化发布流程
原生适配 AI / 脚本调用
输出模式智能切换

Doc index

Problems encountered, contact us →