需要 Node.js 20 或更新版本、npm 和终端。首次读取前,准备受支持的 CLI 会话,或带 campaign:read 的组织 Key;下文会核对目标与范围。
执行前先查操作开放范围与兼容性。
hbd 是用于 Campaign API 和交付记录读取的命令行客户端,hb 和 humanbased 是同一程序的另外两个命令名。公开 beta 包发布在 npmjs,采用 Apache-2.0,无需 GitHub 登录:
npm install --global humanbased@0.1.0-beta.3本例面向 humanbased@0.1.0-beta.3,公开 npm 产物尚待核对。固定版本使练习可复现;humanbased@beta 会跟随 beta 渠道变化。如果安装版本与分配给你的环境不一致,请联系 Humanbased 支持。
准备核查客户反馈时,可直接阅读交付数据质量核查步骤。
如果组织允许你使用 Humanbased monorepo 的源码,可在仓库根目录用 Node.js 20 或更新版本和 pnpm 构建:
pnpm install --frozen-lockfile
pnpm --filter @humanbased/cli build
node packages/cli/dist/hb.js --version使用源码构建时,把下文命令中的 hbd 换成 node packages/cli/dist/hb.js。这条路径面向已获仓库权限的开发者,不代表公开包已发布。
先查看当前版本
hbd --version
hbd --help --json
hbd config profiles list --jsonJSON 帮助和 Profile(目标环境配置)命令不发送网络请求。未配置目标时,CLI 默认连接公开服务;Profile 记录目标地址,不保存凭证。更改已配置目标前,请先查看当前 Profile。
可用 hbd auth login 在浏览器完成该版本支持的登录,也可按下文提供组织授权的 Key。认证后再检查:
hbd auth status
hbd auth whoami --json
hbd capabilities --json核对组织和凭证能力。通过 HB_API_KEY 提供的 Key 优先于已保存的会话。已配置的目标若 API 地址不匹配,CLI 会拒绝请求。
选择凭证
人在终端使用受支持版本的 hbd auth login 时,需要在浏览器完成登录确认。CLI 会话的权限比完整门户会话窄。无人值守的程序应通过运行环境的密钥管理,以 HB_API_KEY 或 --token-stdin 提供组织 API Key。不要把 Key 放在命令行参数、代码库、Profile 或智能体提示词中。
服务器仍按具体活动Developer 组织的一组数据工作及其相关设置核对权限。命令出现在帮助列表里,不代表当前凭证获准执行。遇到 403 时,先用 hbd auth whoami --json 核对身份、当前组织及目标活动,不通过换用他人的凭证扩大范围。
先读取,并检查每次结果
从只读操作开始:
hbd campaign list --limit 5 --json标准输出只有一个 JSON 封套,应同时检查 error.code 和退出码;进度消息在标准错误输出。data.items 为空,表示本次范围没有可见活动。若 data.has_more=true,把返回的 data.next_cursor 传给下一次的 --cursor。--all 会连续读取多页,应在确有需要时使用。
| 退出码 | 含义 |
|---|---|
0 | 该命令按自身规则完成;成功读取回执不表示之前的写入成功。 |
1 | 请求已完成,但没有达到命令的完成条件:文件未通过验证、计划无法应用,或 campaign records pull --all 的导出提前停止。 |
2 | 命令参数无效或请求格式有误。 |
3、4 | 缺少可用凭证或权限不足。 |
5 | 冲突或需要本人决定的结果。 |
6 | 暂时性错误,或输出没有送达;按具体提示重试。 |
7–10 | 服务失败、支出限制、等待超时或契约不匹配;检查 error.code。 |
130 | 命令被中断。 |
浏览器会话用完后执行 hbd auth logout。hbd auth sessions list 和 hbd auth sessions revoke 用于查看与撤销已保存会话;组织 API Key 另行管理。
继续查看命令参考。