# 用 CLI 读取第一个活动


需要 Node.js 20 或更新版本、npm 和终端。首次读取前，准备受支持的 CLI 会话，或带 campaign:read 的组织 Key；下文会核对目标与范围。

> 执行前先查[操作开放范围与兼容性](/zh/api/compatibility)。

`hbd` 是用于 Campaign API 和交付记录读取的命令行客户端，`hb` 和 `humanbased` 是同一程序的另外两个命令名。公开 beta 包发布在 npmjs，采用 Apache-2.0，无需 GitHub 登录：

```sh
npm install --global humanbased@0.1.0-beta.3
```

本例面向 `humanbased@0.1.0-beta.3`，公开 npm 产物尚待核对。固定版本使练习可复现；`humanbased@beta` 会跟随 beta 渠道变化。如果安装版本与分配给你的环境不一致，请联系 [Humanbased 支持](mailto:support@humanbased.ai)。

准备核查客户反馈时，可直接阅读[交付数据质量核查步骤](/zh/api/cli-quality)。

如果组织允许你使用 Humanbased monorepo 的源码，可在仓库根目录用 Node.js 20 或更新版本和 pnpm 构建：

```sh
pnpm install --frozen-lockfile
pnpm --filter @humanbased/cli build
node packages/cli/dist/hb.js --version
```

使用源码构建时，把下文命令中的 `hbd` 换成 `node packages/cli/dist/hb.js`。这条路径面向已获仓库权限的开发者，不代表公开包已发布。

## 先查看当前版本

```sh
hbd --version
hbd --help --json
hbd config profiles list --json
```

JSON 帮助和 Profile（目标环境配置）命令不发送网络请求。未配置目标时，CLI 默认连接公开服务；Profile 记录目标地址，不保存凭证。更改已配置目标前，请先查看当前 Profile。

可用 `hbd auth login` 在浏览器完成该版本支持的登录，也可按下文提供组织授权的 Key。认证后再检查：

```sh
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 或智能体提示词中。

服务器仍按具体活动核对权限。命令出现在帮助列表里，不代表当前凭证获准执行。遇到 `403` 时，先用 `hbd auth whoami --json` 核对身份、当前组织及目标活动，不通过换用他人的凭证扩大范围。

## 先读取，并检查每次结果

从只读操作开始：

```sh
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 另行管理。

继续查看[命令参考](/zh/api/cli)。
