connect-api-cli

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

安装

npm install -g connect-api-cli

验证：

connect-api-cli --version
connect-api-cli --help

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

npx connect-api-cli --help

环境要求

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

配置凭证

在当前工作目录放置 .env（工具会优先读取 ./.env），或自行导出环境变量。 工具支持三种认证模式，默认 client_credentials。推荐服务端集成使用 Service Account（见获取服务端授权）。

模式一：client_credentials（API 客户端，默认）

AGC_AUTH_MODE=client_credentials  # 默认值，可省略
AGC_CLIENT_ID=你的客户端ID
AGC_CLIENT_SECRET=你的客户端密钥

模式二：Service Account（推荐）

在 AGC 控制台创建 Service Account 并下载 *_private.json，本地用私钥签发 PS256 JWT，直接作为 Authorization: Bearer（请求不附带 client_id）。

AGC_AUTH_MODE=service_account
AGC_SA_CREDENTIALS=./your-account_private.json

凭据文件需包含 key_id、private_key、sub_account（其余字段可选）。JWT 有效约 1 小时，过期前会自动重新签发并缓存。

模式三：OAuth 授权码 + 自动刷新

AGC_AUTH_MODE=oauth 时走华为账号浏览器授权码登录。默认端点与 HarmonyBot 插件生产环境对齐，均可用环境变量覆盖：

AGC_AUTH_MODE=oauth
# 多团队账号时必填；仅一个团队时可省略（首次 API 调用自动选定）
# AGC_TEAM_ID=你的团队ID
# 以下均可选，默认与插件生产环境一致
# AGC_OAUTH_CLIENT_ID=117427577
# AGC_OAUTH_AUTH_URL=https://oauth-login.cloud.huawei.com/oauth2/v3/authorize
# AGC_OAUTH_TOKEN_URL=https://connect-api.cloud.huawei.com/api/cag/v1/access-token/generate
# AGC_OAUTH_REFRESH_URL=https://connect-api.cloud.huawei.com/api/cag/v1/access-token/refresh
# AGC_OAUTH_REDIRECT_URI=http://localhost:12306
# AGC_OAUTH_SCOPE=openid profile https://www.huawei.com/auth/agc/publish https://www.huawei.com/auth/agc/develop

OAuth 请求头使用 oauth2Token（不是 Authorization: Bearer），并自动附带 teamId。 通用可选配置：

# 可选，API 主机，默认中国区
# AGC_DOMAIN=connect-api.cloud.huawei.com
# 生成 CSR / P12 时若未传 --sdk-path，可设置 SDK 路径
# HARMONYOS_SDK_PATH=/path/to/harmonyos/sdk

登录与 Token

Access Token / JWT 缓存在 ~/.connect-api-cli-token.json，在过期前约 5 分钟会自动刷新或重新签发。

connect-api-cli auth login    # 获取并写入缓存（oauth 会打开浏览器；service_account 本地签 JWT）
connect-api-cli auth status   # 查看模式、Client ID / Key ID、Token 过期时间与自动刷新状态
connect-api-cli auth logout   # 删除缓存文件

自动刷新：OAuth 模式会保存 refreshToken，accessToken 过期时自动用 refreshToken 换取新 token；Service Account / client_credentials 过期后分别重新签 JWT / 换取 token。仅当 OAuth 刷新失败（如 refreshToken 失效）时才退回重新授权。请求返回 401 时也会触发一次自动刷新并重试。

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

推荐工作流

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

工作流 A：首次配置

1. 确认已配置 .env（client_credentials 的 Client ID/Secret，或 service_account 的 AGC_SA_CREDENTIALS）。
2. connect-api-cli auth login
3. connect-api-cli publish app-id -p <包名> → 获取 appId（若为空可用 publish app-create）
4. connect-api-cli publish app-info -a <appId> → 校验应用信息

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

1. connect-api-cli provision csr-generate --alias mykey（默认写入 .certs/<随机数>/key_<随机数>.* 等；按需加 --sdk-path）
2. connect-api-cli provision cert-create --csr <返回的 csrPath> --cert-name "MyCert" --cert-type 1
3. 从返回 JSON 中记录 certId
4. connect-api-cli provision device-add --devices devices.json（真机调试时需要）
5. connect-api-cli provision profile-create --name "MyProfile" --type 1 --cert <certId> -a <appId> --device-ids <设备ID>

工作流 C：上传构建产物

1. connect-api-cli auth login（如 Token 仍有效可省略）
2. connect-api-cli publish app-id -p <包名>（已知 appId 可跳过）
3. connect-api-cli upload file -a <appId> -f ./build/outputs/default/<name>-default-signed.app -r 1 HarmonyOS 须传 .app。命令会先传到 OBS，再自动调用「更新应用软件包信息」上报；成功 stdout 为 JSON（.objectId、.packageId、.bound）。AGC 控制台只在上报成功后才有记录。测试分发用 -r 6（不上报正式版本，再用 test pkg-add）。仅 OBS、不上报时加 --no-bind。

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

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

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

前提条件

• 应用须已在 AGC 创建（控制台或 publish app-create）
• 已安装 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

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

D3. 获取设备 UDID 并注册

hdc shell bm get --udid
connect-api-cli provision device-list

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

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

connect-api-cli provision device-add --devices devices.json

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

connect-api-cli provision csr-generate --alias mykey --out-dir .certs --sdk-path /Applications/DevEco-Studio.app/Contents/sdk

未指定 --pwd 时，CLI 用 CSPRNG 生成 32 位 hex 密码，只出现在 JSON .pwd（不写文件）。一套材料在 .certs/<随机数>/ 下：key_*.p12 / .csr，cert_*.cer，profile_*.p7b。csr-generate 会把 DevEco material/ 放到该目录旁，不要把签名文件拷到工程根目录。后续步骤用返回的 .csrPath / .cerPath / .p7bPath / .pwd。应用工程可将 .certs/ 自行加入 .gitignore（CLI 不会在该目录写入 .gitignore）。

D5. 创建调试证书

connect-api-cli provision cert-create --csr <csrPath> --cert-name "MyDebugCert" --cert-type 1

从返回中取 certDownloadUrl，下载到 JSON 里的 cerPath：

curl -o <cerPath> "<certDownloadUrl>"

D6. 创建调试 Profile

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

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

curl -o <p7bPath> "<provisionDownloadUrl>"

D7. 核对 bundleName

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

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

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

P12_PWD=$(jq -r '.pwd' <<<'<csr-generate JSON>')
connect-api-cli provision encrypt-pwd --pwd "$P12_PWD" --config-dir "$HOME/.ohos/config"

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

signingConfigs 示例（json5）：

{
  "name": "default",
  "type": "HarmonyOS",
  "material": {
    "certpath": "./.certs/<随机数>/cert_<随机数>.cer",
    "keyAlias": "<别名>",
    "keyPassword": "<encrypt-pwd 输出的 hex>",
    "profile": "./.certs/<随机数>/profile_<随机数>.p7b",
    "signAlg": "SHA256withECDSA",
    "storeFile": "./.certs/<随机数>/key_<随机数>.p12",
    "storePassword": "<encrypt-pwd 输出的 hex>"
  }
}

csr-generate 会把 DevEco 的 material/ 放到 .p12 同级（JSON .materialPath）。不要把签名文件拷到工程根目录。若 .materialPath 为空，再手动：

ln -s ~/.ohos/config/material <storePath>/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 <包名>

命令一览

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

auth

| 子命令 | 说明 | |--------|------| | login | 登录并缓存 Token（oauth 模式打开浏览器授权） | | status | 查看当前模式、Client ID、Token 过期时间与自动刷新状态 | | logout | 清除本地 Token 缓存 |

publish

| 子命令 | 说明 | |--------|------| | app-id | 按包名查询 App ID（-p） | | app-create | 创建应用/元服务（--app-name、--parent-type、--installation-free；应用须 -p，元服务不传；--project-id 可省略以交互选择） | | app-info | 按 App ID 查询应用信息（-a，可选 -l 语言） |

project

| 子命令 | 说明 | |--------|------| | list | 查询项目列表（产出 projectId，stderr 回显供选择） |

upload

对应 Upload Management API 参考。分片流程封装在内部（小于 5MB 单文件，否则自动分片）。

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

provision

证书与密钥

| 子命令 | 说明 | |--------|------| | csr-generate | 生成本地密钥与 CSR（默认 .certs/<随机数>/，文件为 key_*.p12、cert_*.cer、profile_*.p7b；未传 --pwd 时用 CSPRNG 生成密码） | | 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" }

注意事项

• 应用创建：先 project list 让用户选定 projectId，再 publish app-create（--project-id、--app-name、--parent-type：2 游戏 / 13 应用，--installation-free：0 应用须 -p / 1 元服务不传包名；TTY 下可省略 --project-id 交互选择）。也可在控制台创建。若 publish app-id 返回空 appids，多为包名未注册或应用未创建。
• API 客户端与 403：客户端仅能访问其团队/项目下的资源；403 常见原因为权限不足，请在「用户与访问 → API 客户端」核对权限范围。
• bundleName 与 Profile：app.json5 的 bundleName 须与 AGC 应用包名、.p7b 一致。
• 密码与 material：csr-generate 默认把每套材料写入 .certs/<随机数>/（key_*.p12、cert_*.cer、profile_*.p7b，JSON .storePath / .filename）；未传 --pwd 时用安全随机数生成 P12 密码。hvigor 所需 material/ 会放到 .p12 同级，不要拷到工程根目录。build-profile.json5 需使用 AES-128-GCM 加密后的密码（encrypt-pwd 输出）。
• 设备类型（deviceType 等场景）：1 运动手表，2 智能手表，4 手机，5 平板，8 智慧屏，19 PC / 2in1（以 AGC 最新文档为准）。
• JSON 文件入参：--devices、--domains、--acls 等需传入文件路径，内容为合法 JSON。
• 逗号分隔 ID：--cert-ids、--device-ids、--fps 等使用英文逗号分隔，如 id1,id2。
• 输出格式：业务结果（JSON）打印到 stdout，进度提示与错误信息打印到 stderr，因此 connect-api-cli ... 2>/dev/null | jq 可安全解析（v1.1.1 起）。auth login 仅打印登录状态与 Token 片段，避免泄露完整 Token。
• 退出码：命令失败时错误写入 stderr，但进程退出码仍为 0。脚本中请通过解析输出（.ret.code）或检查 stderr 判断成功，不要依赖 && 或 $?。
• 敏感信息：勿将 .env、.certs/、*.p12、~/.connect-api-cli-token.json 提交到版本库。调试与发布签名材料均在工程 .certs/。

作为 npm 库使用

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

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

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

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

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