$ npm install --global @createitv/agc-cli && agc version让每一次发布沿着 同一条红线前进。
用一套 Go 命令发现、预演并调用 AppGallery Connect API,为开发者、CI 和 Coding Agent 提供稳定 JSON。
$ agc auth check --pretty
{
"data": {
"name": "production",
"mode": "service-account",
"active": true
},
"affordances": {
"next": "agc publishing endpoints"
}
}已解析项目 Profile · 默认 dry-run
安装 agc CLI
用系统包管理器安装。
Windows、macOS 和 Linux CI 可通过同一条 NPM 命令无人值守安装。开发电脑仍可使用 Homebrew 或 Scoop 原生包。
$ brew tap createitv/tap && brew install agc-cli && agc versionPS> if (!(Get-Command scoop -ErrorAction SilentlyContinue)) { Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force; irm get.scoop.sh | iex }; scoop bucket add createitv https://github.com/Createitv/scoop-bucket; scoop install agc-cli; agc versionAgent Skills
让 Coding Agent 真正理解 AppGallery Connect 工作流。
6 个可移植 Skills 参考 asc-cli 的任务分层方式设计。可以全部安装,也可以只选择一个工作流;每个 Skill 都支持查看源码、直接下载和通过 GitHub 参与完善。
提交一个 Skill$ agc skills install --agent codex --globalagc-cli-usage通用命令发现、dry-run 预演、授权执行和远程结果验证。
agc skills install --name agc-cli-usage --agent codex --globalagc-auth凭据 Profile、whoami、OAuth 团队查询和权限诊断。
agc skills install --name agc-auth --agent codex --globalagc-publishing应用资料、软件包、提交审核、分阶段发布和发布状态验证。
agc skills install --name agc-publishing --agent codex --globalagc-testing测试版本、群组、测试用户、邀请链接、反馈和版本转正。
agc skills install --name agc-testing --agent codex --globalagc-reports分发、安装、付费、留存和鸿蒙元服务报表导出。
agc skills install --name agc-reports --agent codex --globalagc-cicd跨平台固定版本安装、受保护凭据、dry-run 门禁和 CI 验证。
agc skills install --name agc-cicd --agent codex --global发布轨道
上下文向前流动,密钥留在本地。
每个阶段只完成一件事。凭据保存在本机,项目上下文可以安全共享,写入类 API 必须显式确认。
鉴权
PS256 / OAuth
PROFILE
项目自动绑定
软件包
上传与状态
发布
确认后调用
Profile 自动绑定
每个项目只选择一次,临时切换时再覆盖。
在 .agc/project.json 中绑定 production。命令会按固定优先级解析,也可以用 --profile staging 完成一次性切换。
- 1命令行显式覆盖
--profile staging - 2项目默认 Profile
.agc/project.json - 3全局激活账户
~/.agc/credentials.json
{
"appId": "123456789",
"projectId": "987654321",
"packageName": "com.example.app",
"profile": "production"
}接口注册表
先发现 API,再编写请求。
每个条目都包含 method、path、参数位置、CLI 命令、REST 路由和 dry-run 调用方式。
当前家族 / storage
云存储
文件上传下载、元数据与文件列表。
agc storage endpoints --output tableagc storage status --pretty/api/v1/storage全部接口 6
展开接口查看已登记参数与命令;完整协议、响应字段及权限以官方文档为准。
PUT上传文件upload-file/{bucket_name}/{object_name}
此接口用于上传文件。
开发者调用华为 API
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
object_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
bucket_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
client_id | header | 否 | string | 客户端ID,获取方法参考创建API客户端。 |
productId | header | 是 | string | 项目ID,查询方法可参见查询项目ID。 |
Authorization | header | 否 | string | 认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取Token中获取的access_token。 |
X-Agc-File-Size | header | 否 | string | 文件大小,断点续传时为必选。 |
X-Agc-File-Offset | header | 否 | string | 文件偏移量,断点续传的起始位置非零时为必选。 |
X-Agc-Sha256 | header | 否 | string | 文件的SHA256值,断点续传时为必选。 |
X-Agc-Content-Type | header | 否 | string | 文件类型。 默认值:application/octet-stream |
X-Agc-Content-Disposition | header | 否 | string | 文件打开方式。 |
X-Agc-Content-Encoding | header | 否 | string | HTTP标准头部Content-Encoding。 |
X-Agc-Cache-Control | header | 否 | string | HTTP标准头部Cache-Control。 |
X-Agc-Content-Language | header | 否 | string | HTTP标准头部Content-Language。 |
X-Agc-meta-* | header | 否 | string | 可以在请求中加入以“X-Agc-meta-”开头的消息头,用于加入自定义的元数据,以便对文件进行自定义管理。当用户获取此文件或查询此文件元数据时,加入的自定义元数据将会在返回消息的头部出现。 X-Agc-meta-仅标记此header是传递元数据,并非元数据key的一部分。例如,您传入的是“X-Agc-meta-test: test metadata”,保存的数据实例为“test: test metadata”。 说明 元数据名称相同则覆盖。自定义的部署不区分大小写,最后记录均为小写的方式。 |
X-Agc-Trace-Id | header | 否 | string | 单个文件请求的Traceid。可不填或者随机生成,用于日志打印跟踪。 |
file | file | 是 | string | — |
请求体: file
查看接口定义
agc storage upload-file --pretty
本地 REST 定义地址
/api/v1/storage/endpoints/upload-file
调用预演(先填写所需参数)
agc storage upload-file --invoke --dry-run=true --body body.json查看接口参考文档 ↗
GET下载文件download-file/{bucket_name}/{object_name}
此接口用于使用用户身份认证方式下载文件。
开发者调用华为 API
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
object_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
bucket_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
Authorization | header | 否 | string | 认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取Token中获取的access_token。 |
client_id | header | 否 | string | 客户端ID,获取方法参考创建API客户端。 |
productId | header | 是 | string | 项目ID,查询方法可参见查询项目ID。 |
Range | header | 否 | string | HTTP标准协议头,用于指定第一个字节和最后一个字节的位置,告诉服务器想获取的文件范围。如未指定,则获取整个文件。 例如一个文件有900个字节,其范围为0-899,则: Range: bytes=500- 表示读取该文件的500-899字节。 Range: bytes=500-699 表示读取该文件的500-699字节。 |
If-Modified-Since | header | 否 | string | 一个条件式请求首部。 服务器只在所请求的资源在给定的时间之后对内容进行过修改的情况下才会将资源返回,状态码为200 。如果请求的资源在给定的时间之后未经修改,则返回一个不带消息主体的304响应。 格式:<day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT 举例:Mon, 10 Apr 2023 07:28:00 GMT 说明 If-Modified-Since只可以用在GET或HEAD请求中。当与If-None-Match 一同出现时,If-Modified-Since会被忽略,除非服务器不支持If-None-Match。 |
If-None-Match | header | 否 | string | 一个条件式请求首部。 对于GET和HEAD方法,当且仅当服务器上没有任何资源的ETag属性值与这个首部中列出的相匹配时,服务器端会才返回所请求的资源,响应码为200 ,否则返回304。其他方法暂不实现。 格式:If-None-Match: "<etag_value>" 不支持通配符*,不支持弱比较算法。 |
X-Agc-Trace-Id | header | 否 | string | 单个文件请求的Traceid。可不填或者随机生成,用于日志打印跟踪。 |
查看接口定义
agc storage download-file --pretty
本地 REST 定义地址
/api/v1/storage/endpoints/download-file
调用预演(先填写所需参数)
agc storage download-file --invoke --dry-run=true查看接口参考文档 ↗
DELETE删除文件delete-file/{bucket_name}/{object_name}
此接口用于删除文件。
开发者调用华为 API
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
object_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
bucket_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
Authorization | header | 否 | string | 认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取Token中获取的access_token。 |
client_id | header | 否 | string | 客户端ID,获取方法参考创建API客户端。 |
productId | header | 是 | string | 项目ID,查询方法可参见查询项目ID。 |
X-Agc-Trace-Id | header | 否 | string | 单个文件请求的Traceid。可不填或者随机生成,用于日志打印跟踪。 |
查看接口定义
agc storage delete-file --pretty
本地 REST 定义地址
/api/v1/storage/endpoints/delete-file
调用预演(先填写所需参数)
agc storage delete-file --invoke --dry-run=true查看接口参考文档 ↗
GET获取文件元数据get-metadata/{bucket_name}/{object_name}?metadata=query
此接口用于获取文件元数据。
开发者调用华为 API
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
object_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
bucket_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
Authorization | header | 否 | string | 认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取Token中获取的access_token。 |
client_id | header | 否 | string | 客户端ID,获取方法参考创建API客户端。 |
productId | header | 是 | string | 项目ID,查询方法可参见查询项目ID。 |
X-Agc-Trace-Id | header | 否 | string | 单个文件请求的Traceid。可不填或者随机生成,用于日志打印跟踪。 |
查看接口定义
agc storage get-metadata --pretty
本地 REST 定义地址
/api/v1/storage/endpoints/get-metadata
调用预演(先填写所需参数)
agc storage get-metadata --invoke --dry-run=true查看接口参考文档 ↗
GET修改文件元数据update-metadata/{bucket_name}/{object_name}?metadata=update
此接口用于修改文件元数据。
开发者调用华为 API
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
object_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
bucket_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
Authorization | header | 否 | string | 认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取Token中获取的access_token。 |
client_id | header | 否 | string | 客户端ID,获取方法参考创建API客户端。 |
productId | header | 是 | string | 项目ID,查询方法可参见查询项目ID。 |
X-Agc-Trace-Id | header | 否 | string | 单个文件请求的Traceid。可不填或者随机生成,用于日志打印跟踪。 |
X-Agc-Content-Type | header | 否 | string | 文件类型。 默认值:application/octet-stream |
X-Agc-Content-Disposition | header | 否 | string | 文件打开方式。 |
X-Agc-Content-Encoding | header | 否 | string | HTTP标准头部Content-Encoding。 |
X-Agc-Cache-Control | header | 否 | string | HTTP标准头部Cache-Control。 |
X-Agc-Content-Language | header | 否 | string | HTTP标准头部Content-Language。 |
X-Agc-meta-* | header | 否 | string | 可以在请求中加入以“X-Agc-meta-”开头的消息头,用于加入自定义的元数据,以便对文件进行自定义管理。当用户获取此文件或查询此文件元数据时,加入的自定义元数据将会在返回消息的头中出现。 示例:X-Agc-meta-test: test metadata 保存实例为:test: test metadata 说明 元数据名称相同则覆盖。自定义的部署不区分大小写,最后记录均为小写的方式。X-Agc-meta-仅标记此header是传递元数据,并非元数据key的一部分。 目录对象不支持自定义元数据,所以此接口不支持目录对象。 |
查看接口定义
agc storage update-metadata --pretty
本地 REST 定义地址
/api/v1/storage/endpoints/update-metadata
调用预演(先填写所需参数)
agc storage update-metadata --invoke --dry-run=true查看接口参考文档 ↗
GET列举文件list-files/{bucket_name}
此接口用于列举文件。
开发者调用华为 API
| 参数 | 位置 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
bucket_name | path | 是 | string | Storage instance or object path; percent-encoded exactly once. |
client_id | header | 否 | string | 客户端ID,获取方法参考创建API客户端。 |
productId | header | 是 | string | 项目ID,查询方法可参见查询项目ID。 |
Authorization | header | 否 | string | 认证信息,格式为“Authorization: Bearer ${access_token}”。access_token为获取Token中获取的access_token。 |
X-Agc-Trace-Id | header | 否 | string | 单个文件请求的Traceid。可不填或者随机生成,用于日志打印跟踪。 |
max-keys | query | 否 | string | 指定返回文件个数的最大值,默认值为50,取值范围为[1,1000]。 超出范围时,按照默认值进行处理。 如果因为max-keys的设置无法一次完成列举,返回结果会附加NextMarker元素作为下一次列举的marker。 |
marker | query | 否 | string | 指定返回哪个标识符之后的文件,按照文件Key的UTF-8字典顺序排序。 |
prefix | query | 否 | string | 列举以指定的字符串prefix开头的文件。 |
delimiter | query | 否 | string | 将文件名按照特定字符分割的分割符。 注意 当前仅支持传空值或正斜杠(/),正斜杠(/)编码后为%2F。 如果指定了prefix参数,按delimiter对所有文件名进行分割,多个文件分割后从prefix到第一个delimiter之间相同的部分会形成一条CommonPrefixes。 如果未携带prefix参数,按delimiter对所有文件名进行分割,多个文件分割后从文件名开始到第一个delimiter之间相同的部分形成一条CommonPrefixes。 |
查看接口定义
agc storage list-files --pretty
本地 REST 定义地址
/api/v1/storage/endpoints/list-files
调用预演(先填写所需参数)
agc storage list-files --invoke --dry-run=true查看接口参考文档 ↗
agc-cli 是什么,适合谁使用?
agc-cli 是 Createitv 开源的华为 AppGallery Connect 命令行工具,安装后的命令名是 agc。它面向鸿蒙和华为应用开发者,将接口发现、凭据 Profile、请求预演与 API 调用组织成可复用命令,适合需要维护应用资料、测试用户、商品和报表的个人开发者与团队。
项目与使用指南: GitHub · 使用指南 · Issues
GEO · AEO · LLMO
面向 AI Agent 的可读取文档
这些公开文件提供项目事实、任务选择、安全边界、Skills 和完整接口契约。Coding Agent 可以直接读取,无需执行 JavaScript、登录或猜测页面结构。
常见问题
agc-cli 是华为官方工具吗?
不是。agc-cli 是 Createitv 维护的独立开源项目,使用 MIT 许可证。它基于华为 AppGallery Connect API 参考文档组织接口,不代表华为官方产品或官方支持服务。
如何在 macOS、Windows 和 Linux 安装 agc-cli?
已安装 Node.js 18+ 时,三个系统都可运行 npm install --global @createitv/agc-cli。macOS 也可使用 Homebrew,Windows 也可使用 Scoop。安装后运行 agc version 检查版本。
agc-cli 免费吗,需要付费账号吗?
agc-cli 使用 MIT 许可证,可免费使用和修改。调用华为 API 需要自己的 AppGallery Connect 账号、凭据和相应权限;华为平台服务的费用和限制以华为说明为准。浏览官网接口和使用 CLI 查看接口定义无需登录。
如何开始第一次应用信息查询?
先用 agc auth login --service-account-file ~/.agc/service-account.json --name production 保存凭据,再用 agc init --app-id YOUR_APP_ID --default-profile production 绑定项目。运行 agc publishing app-info-query --invoke --query appId=YOUR_APP_ID --query lang=zh-CN 预演请求,确认后增加 --dry-run=false 发送请求。接口要求 client_id 时显式补上请求头。
156 个接口是否都完成了生产验证?
156 表示注册表中的接口条目数量,分属 13 个 API 家族,不代表每个接口都已完成生产验证。注册表展示已登记参数和调用入口;完整请求、响应、权限与业务前置条件以每个接口链接的参考文档为准。
默认 dry-run 会修改我的应用吗?
不会。带 --invoke 的接口命令默认构建并预览请求,不发送远程请求。真实调用需显式设置 --dry-run=false;调用前应检查目标应用、所选凭据和参数。
可以把 agc-cli 用在脚本或 AI Agent 中吗?
可以。默认 JSON 输出适合脚本处理,agc capabilities 和 agc endpoints 提供能力发现;agc web-server 提供本地 REST 接口,agc openapi 导出接口契约。命令模板帮助导航,但不能替代业务状态检查或审核判断。
如何安装 agc-cli 的 Codex 或 Claude Agent Skills?
先安装 agc-cli,再运行 agc skills list 查看 6 个任务型 Skills。使用 agc skills install --agent codex --global 安装全部 Skills,或增加 --name agc-publishing 只安装发布 Skill。也可以从官网直接下载对应的 SKILL.md。
项目 Profile 会自动填入所有接口参数吗?
项目配置可以绑定默认凭据 Profile,临时切换时使用 --profile。应用 ID、语言、请求头和请求体等接口参数仍需按接口要求显式提供。不要将 Service Account 私钥或凭据文件提交到 Git。
按 API 家族浏览完整参考
内容更新:
快速开始
三条命令,建立可检查的项目工作区。
请将占位符替换为 AppGallery Connect 的真实值。第二条命令会让该项目自动选择对应 Profile。
保存凭据 Profile
推荐使用 Service Account。密钥会以受限权限保存在 ~/.agc/credentials.json。
$ agc auth login --service-account-file ~/.agc/service-account.json --name production绑定当前项目
保存项目资料与默认凭据 Profile;调用接口时仍按要求填写应用 ID 等参数。
$ agc init --app-id <app-id> --project-id <project-id> --package-name com.example.app --default-profile production调用前先检查
接口命令默认 dry-run。确认 method 与 URL 后,再明确执行真实请求。
$ agc publishing app-info-query --invoke --query appId=<app-id> --dry-run=false本地命令中心
浏览器看到的,就是 CLI 使用的同一份注册表。
需要实时能力数据时启动本地 REST 服务;未启动时,官网仍会作为完整参考界面工作。
agc web-server --addr :8421/api/v1/capabilities家族与下一步操作/api/v1/endpoints全部接口条目/api/v1/openapi.json机器可读契约/api/v1/:family/endpoints/:id/invoke默认 dry-run