agc-api-cli

v1.0.3

Published

2 months ago

AppGallery Connect API CLI Tool

Downloads

278

0High
0Medium
0Low

legend87

agc-api-cli

面向 AppGallery Connect (AGC) 的命令行工具，封装常用 REST 能力：发布与上传、证书与 Profile、设备与指纹、ACL、域名配置等，并支持 HarmonyOS 调试签名材料生成、DevEco 密码加密、与 hvigor / hdc 联动的端到端上机调试指引。成功响应多数以 JSON 打印，便于配合 jq 等工具处理。

安装

npm install -g agc-api-cli

验证：

agc-cli --version
agc-cli --help

不全局安装时，可在项目目录使用 npx（需本地已配置凭证环境变量或 .env）：

npx agc-api-cli --help

环境要求

Node.js：建议当前 LTS 版本。
AGC API 客户端：在 AGC 控制台 → 用户与访问 → API 客户端 创建，并具备对应团队/应用权限。

配置凭证

在当前工作目录放置 .env（工具会优先读取 ./.env），或自行导出环境变量：

AGC_CLIENT_ID=你的客户端ID
AGC_CLIENT_SECRET=你的客户端密钥
# 可选，API 主机，默认中国区
# AGC_DOMAIN=connect-api.cloud.huawei.com

生成 CSR / P12 时若未传 --sdk-path，可设置：

HARMONYOS_SDK_PATH=/path/to/harmonyos/sdk

登录与 Token

Access Token 缓存在 ~/.agc-cli-token.json，在过期前约 5 分钟会自动刷新。

agc-cli auth login    # 获取并写入缓存
agc-cli auth logout   # 删除缓存文件

多数子命令在调用 API 前会隐式拉取有效 Token；首次使用建议先执行 auth login 确认凭证无误。

推荐工作流

以下命令均以全局安装后的 agc-cli 为例；若使用本地脚本，将前缀替换为 node /path/to/cli.js 即可。

工作流 A：首次配置

确认已配置 .env（AGC_CLIENT_ID、AGC_CLIENT_SECRET）。
agc-cli auth login
agc-cli publish app-id -p <包名> → 获取 appId
agc-cli publish app-info -a <appId> → 校验应用信息

工作流 B：证书 + Profile（调试签名）

agc-cli provision csr-generate --alias mykey --out-dir ./keys（按需加 --sdk-path）
agc-cli provision cert-create --csr ./keys/mykey.csr --cert-name "MyCert" --cert-type 1
从返回 JSON 中记录 certId
agc-cli provision device-add --devices devices.json（真机调试时需要）
agc-cli provision profile-create --name "MyProfile" --type 1 --cert <certId> -a <appId> --device-ids <设备ID>

工作流 C：上传构建产物

agc-cli auth login（如 Token 仍有效可省略）
agc-cli publish app-id -p <包名>（已知 appId 可跳过）
agc-cli upload file -a <appId> -f ./app-release.hap -r 1

-r：发布类型，例如 1 全量、6 HarmonyOS 测试。-c：可选，0 / 1 中国大陆相关标记。

工作流 D：端到端签名 → 构建 → 上机调试

结合 agc-cli、DevEco 配套工具（hvigorw、ohpm、hdc）完成全流程。

前提条件

应用必须已在 AGC 控制台创建（开放接口通常不支持「新建应用」）
已安装 DevEco Studio、Java
真机已通过 USB 连接（hdc list targets 可看到设备）

macOS 典型路径（请按本机安装位置调整）

SDK:        /Applications/DevEco-Studio.app/Contents/sdk
hvigorw:    /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw
ohpm:       /Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm
hdc:        /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc
签名工具:   /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/lib/hap-sign-tool.jar

D1. 设置 PATH

export PATH="/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH"

D2. 登录并获取 App ID

agc-cli auth login
agc-cli publish app-id -p <包名>

D3. 获取设备 UDID 并注册

hdc shell bm get --udid
agc-cli provision device-list

未注册则准备 devices.json（示例）：

[{"deviceName":"MyPhone","udid":"<UDID>","deviceType":4}]

agc-cli provision device-add --devices devices.json

D4. 生成签名材料（CSR + P12）

agc-cli provision csr-generate --alias mykey --out-dir ./sign_keys --sdk-path /Applications/DevEco-Studio.app/Contents/sdk

未指定 --pwd 时，默认密钥库密码为 123456。

D5. 创建调试证书

agc-cli provision cert-create --csr ./sign_keys/<文件名>.csr --cert-name "MyDebugCert" --cert-type 1

从返回中取 certDownloadUrl，下载 .cer：

curl -o ./sign_keys/<文件名>.cer "<certDownloadUrl>"

D6. 创建调试 Profile

agc-cli provision profile-create --name "MyDebugProfile" --type 1 --cert <certId> -a <appId> --device-ids <设备ID>

从返回中取 provisionDownloadUrl，下载 .p7b：

curl -o ./sign_keys/<文件名>.p7b "<provisionDownloadUrl>"

D7. 核对 bundleName

AppScope/app.json5 中的 bundleName 必须与 AGC 上注册的包名完全一致，且与 Profile（.p7b）一致，否则安装会失败。

D8. 加密密码并配置 build-profile.json5

build-profile.json5 中的密钥密码需为 AES-128-GCM 加密后的十六进制字符串（通常 ≥32 字符）。使用：

agc-cli provision encrypt-pwd --pwd <你的P12密码>

输出 JSON 中的 keyPassword、storePassword 填入 signingConfigs.material。若 DevEco 配置目录不在默认位置 ~/.ohos/config，使用 --config-dir 指定。

signingConfigs 示例（json5）：

{
  "name": "default",
  "type": "HarmonyOS",
  "material": {
    "certpath": "./sign_keys/<文件名>.cer",
    "keyAlias": "<别名>",
    "keyPassword": "<encrypt-pwd 输出的 hex>",
    "profile": "./sign_keys/<文件名>.p7b",
    "signAlg": "SHA256withECDSA",
    "storeFile": "./sign_keys/<文件名>.p12",
    "storePassword": "<encrypt-pwd 输出的 hex>"
  }
}

加密所用密钥材料在 ~/.ohos/config/material/。material/ 必须在 .p12 同级目录可被构建工具访问，必要时建立软链接：

ln -s ~/.ohos/config/material ./sign_keys/material

D9. 构建签名 HAP

cd <项目根目录>
ohpm install
hvigorw assembleHap --mode module -p module=entry@default -p product=default -p buildMode=debug --no-daemon

典型产物路径：entry/build/default/outputs/default/entry-default-signed.hap（以工程模块名为准）。

D10. 安装并启动

hdc install ./entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b <包名>

命令一览

以下为简要说明；参数细节以 agc-cli <分组> <子命令> --help 为准。

`auth`

| 子命令 | 说明 | |--------|------| | login | 登录并缓存 Token | | logout | 清除本地 Token 缓存 |

`publish`

| 子命令 | 说明 | |--------|------| | app-id | 按包名查询 App ID（-p） | | app-info | 按 App ID 查询应用信息（-a，可选 -l 语言） |

`upload`

| 子命令 | 说明 | |--------|------| | file | 上传文件（-a App ID，-f 本地路径，可选 -r、-c） |

`provision`

证书与密钥

| 子命令 | 说明 | |--------|------| | csr-generate | 生成本地密钥与 CSR（--alias，可选 --pwd、--out-dir、--sdk-path 等） | | encrypt-pwd | 加密 P12 密码，输出 keyPassword / storePassword | | cert-create | 申请证书（--csr、--cert-name、--cert-type） | | cert-list | 证书列表（可选 -t、--cert-ids） | | cert-delete | 删除证书（--cert-ids 逗号分隔） |

设备

| 子命令 | 说明 | |--------|------| | device-add | 添加设备（--devices JSON 文件） | | device-list | 设备列表（分页、排序等选项） | | device-delete | 删除设备（--device-ids） |

Profile

| 子命令 | 说明 | |--------|------| | profile-create | 创建 Profile（--name、--type、--cert、-a，可选 --device-ids、--acls） | | profile-list | Profile 列表（-a，可选 --profile-id、--from、--max） | | profile-update | 更新 Profile 关联设备（--id、--device-ids） | | profile-delete | 删除 Profile（--id） |

证书指纹

| 子命令 | 说明 | |--------|------| | fp-add / fp-list / fp-delete | 按 App ID 维护指纹列表（--fps 逗号分隔） |

ACL

| 子命令 | 说明 | |--------|------| | acl-apply | 申请受限 ACL（-a、--acls JSON 文件，可选 --attachment） | | acl-status | 查询申请状态（-a） | | acl-query | 查询已授予 ACL（-a） |

acl-apply 的 JSON 示例：

[
  { "name": "权限标识", "reason": "申请原因说明" }
]

`domain`

| 子命令 | 说明 | |--------|------| | query | 查询域名配置（-a、-c server|business） | | update | 新增或更新域名（-a、-c、--domains JSON 文件） | | config | 查询域名修改次数与上限（-a） | | verify-file | 下载域名校验文件（-a、-o 输出路径） | | pre-check | 业务域名预检（-a、--domain JSON 文件） |

update 的 domains 示例：

[
  { "type": "httpRequest", "value": "https://api.example.com" }
]

pre-check 的 domain 示例：

{ "type": "webView", "value": "https://www.example.com" }

注意事项

应用创建是手动的：AGC REST API 不支持在开放平台侧「从零创建应用」。须先在控制台创建应用；若 publish app-id 返回空 appids，多为包名未注册或应用未创建。
API 客户端与 403：客户端仅能访问其团队/项目下的资源；403 常见原因为权限不足，请在「用户与访问 → API 客户端」核对权限范围。
bundleName 与 Profile：app.json5 的 bundleName 须与 AGC 应用包名、.p7b 一致。
密码与 material：build-profile.json5 需使用 AES-128-GCM 加密后的密码（encrypt-pwd 输出）。密钥材料在 ~/.ohos/config/material/；构建时需保证 material/ 在 .p12 同级目录可用（见工作流 D8 软链接说明）。
设备类型（deviceType 等场景）：1 运动手表，2 智能手表，4 手机，5 平板，8 智慧屏，19 PC / 2in1（以 AGC 最新文档为准）。
JSON 文件入参：--devices、--domains、--acls 等需传入文件路径，内容为合法 JSON。
逗号分隔 ID：--cert-ids、--device-ids、--fps 等使用英文逗号分隔，如 id1,id2。
输出格式：业务结果多为 JSON，可配合 jq 解析；auth login 仅打印登录状态与 Token 片段，避免泄露完整 Token。
敏感信息：勿将 .env、~/.agc-cli-token.json 提交到版本库。

作为 npm 库使用

若要在 Node 项目中直接调用封装好的服务（而非 CLI），可安装依赖后从包入口导入。当前入口会导出例如 AuthService、PublishService、UploadService、ProvisionService 以及 HTTP / 配置相关模块；CLI 中用于签名辅助的 SignService、域名相关的 DomainService 若要在代码中复用，需自行从源码路径引用或在本仓库扩展导出。

import { AuthService, PublishService, UploadService, ProvisionService } from 'agc-api-cli';

// 需已配置 AGC_CLIENT_ID / AGC_CLIENT_SECRET（及可选 AGC_DOMAIN）

类型与完整导出列表以安装后的 dist/index.d.ts 为准。

包名：agc-api-cli（npm） · 可执行命令：agc-cli

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

agc-api-cli

安装

环境要求

配置凭证

登录与 Token

推荐工作流

工作流 A：首次配置

工作流 B：证书 + Profile（调试签名）

工作流 C：上传构建产物

工作流 D：端到端签名 → 构建 → 上机调试

命令一览

auth

publish

upload

provision

domain

注意事项

作为 npm 库使用

`auth`

`publish`

`upload`

`provision`

`domain`