# @customerio/cli 中文文档

规范地址：https://npmcn.com/package/%40customerio/cli/

版本：0\.0\.37
npm 元数据更新时间：2026-11-02T20:31:37.356Z
中文译文更新时间：2026-11-11T05:23:22.061Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40customerio/cli
原文对照：https://npmcn.com/package/%40customerio/cli/?lang=original
项目主页：https://github.com/customerio/cli#readme
源码仓库：https://github.com/customerio/cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：19.2 kB，5 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=16
- 运行依赖：0 个
- 首次发布：2026-04-28T21:24:05.714Z
- 最新版本发布：2026-11-02T20:31:37.008Z
- 近 30 天下载量：11311（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

客户首个CLI.io APIs代理

## 安装

```sh
npm install @customerio/cli
```

也可以使用：`pnpm add @customerio/cli`、`yarn add @customerio/cli`、`bun add @customerio/cli`

## README

# 客户.io CLI(`cio`(中文(简体) )

客户首个CLI.io APIs.

**800+出行路线+100+CDP 管道路线,每端码为0.** 单人 `cio api <path>` 命令覆盖每个终点。 每个命令都会返回结构化的JSON来出局. 每个错误都会将结构化的JSON返回到 stderr.

AI代理是主要消费者. 使用 `cio schema` 在召唤他们之前先回顾一下终点.

## 安装

```bash
npm i -g @customerio/cli
cio --help
```

要从源头构建 :

```bash
go install github.com/customerio/cli@latest
```

## 卸载

```bash
# If installed via npm
npm uninstall -g @customerio/cli

# If installed via go install
rm -f "$(go env GOPATH)/bin/cio"
```

要删除已存储的证书和缓存数据 :

```bash
rm -rf ~/.cio
```

## 安装代理技能

这回转船a [SKILLL.MD (英语)](https://npmcn.com/package/%40customerio/cli/skills/cio/SKILL.md) 所以克劳德代码,光标,代码,Windsurf,以及其他支持的代理 [打开代理技能](https://github.com/vercel-labs/skills) 懂得驾驶CLI.

CLI 可以直接安装当前技能 :

```bash
# Installs the bootstrap skill; prompts for global (~/.claude, ~/.agents)
# vs. project (./.claude, ./.agents)
cio skills install

cio skills install --global          # install for every project
cio skills install --project         # install into the current directory
cio skills install --target claude   # Claude Code only (use --target codex for Codex)
cio skills install --dry-run         # show what would be written
cio skills install --force           # overwrite an existing SKILL.md
```

这只安装了Client.io riottrap技能——它的 `SKILL.md` 路由索引写入 `<target>/skills/<name>/` 克劳德代码( Claude Code) (`.claude`和公开代理技能公约(`.agents`)克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 所有其他参考文献(Journey, CDP, Design Studio, 配方)均由后端服务,并按要求通过 `cio skills read <skill>`,因此没有其它内容是本地复制的,内容保持不变.

或者通过开放代理技能工具安装:

```bash
npx skills add customerio/cli
```

## 认证

使用CLI 软件 **服务账户符号** (单位:千美元)`sa_live_...`用于认证。 这些通过OAuth 2.0客户端证书交换短寿命的JWT,就像 `gh auth`。 。 。 .

### 新到客户。 io?

从 CLI 创建账户 . `start` 电子邮件给您一个6位数的代码,以及 `verify` 检查它,创建账户并保存其证书,所以你 之后不需要登录.

```bash
cio auth signup start --json '{"email":"you@example.com"}'

cio auth signup verify --json '{
  "email": "you@example.com",
  "code": "123456",
  "company_name": "Acme",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "data_center": "us"
}'
```

`data_center` 实值 `us` 或者说 `eu`。AI代理可以为用户运行此功能; 完整 流量在 `cio skills read cio/auth.md`。 。 。 .

### 登录

```bash
# Interactive — prints the browser login URL, then prompts for the minted token
cio auth login

# Read from stdin (for CI/automation; login still auto-discovers region)
echo "$SA_TOKEN" | cio auth login --with-token

# Verify auth works
cio auth status

# Print raw token
cio auth token

# Logout
cio auth logout
```

### 调试解析命令

1.  `--token` 旗帜(最高优先级)
2.  `CIO_TOKEN` 环境变量
3.  `~/.cio/config.json` 文件( 最低优先级)

使用时 `CIO_TOKEN` 或者说 `--token` 直接根据正常命令,您可以 还需要 `CIO_REGION=us|eu` 或者说 `--api-url`。 。 。 .

### 简介

保留多个证书集——生产,中转,多个客户账户 在一个配置文件中,并在它们之间切换。 每张相片都有自己的标语, 区域,以及可选的自定义基础 URL.

```bash
# Log into a named profile (custom --api-url is remembered; switches to it)
echo "$STAGING_TOKEN" | cio auth login --profile staging --with-token --api-url https://<staging-host>

# List profiles (the saved default is marked current)
cio profile list

# Use a profile for one command…
cio --profile staging api /v1/campaigns
# …or a whole session
export CIO_PROFILE=staging

# Change the default, or remove a profile
cio profile use default
cio profile remove staging
```

剖面分辨率 : `--profile` 旗帜 □ `CIO_PROFILE` \* 储存 `current_profile` → `default`中,将移动到 `default` 配置自动。 配置文件名称可能包含字母,数字, `.`, (中文(简体) ), `-`, (中文(简体) ), 财务报告和审定财务报表 `_`。 。 。 .

`cio auth login` 无 `--profile` 重新校正任何配置文件 目前选中, 并不总是 `default` - 通过 `--profile <name>` 目标a 具体一个. `cio profile list` 标记已保存的默认值( e)`current_profile`, (中文(简体) ), 每个命令 `--profile` 编号 : `CIO_PROFILE` 覆盖不变 .

### 如何运作

1.  您提供服务账户代号( Y)`sa_live_...` 从客户.io UI 账户设置 管理API证书 服务账户),或 `cio auth signup verify` 为新账户保存一个
2.  CLI通过JWT交换 `POST /v1/service_accounts/oauth/token`
3.  JWT 本地缓存, 过期时自动刷新
4.  所有 API 调用 `Authorization: Bearer <jwt>`

### 覆盖每个命令

```bash
cio --token sa_live_xxx api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'
CIO_TOKEN=sa_live_xxx cio api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'
```

## 使用量

使用 `cio api <path>` 用于任何 API 端点。 路径占位符从 `--params`。HTTP 方法默认为获取(如果 `--json` ); 以 `-X`数字 :

`--params` 使用 JSON 对象; URL- query 语法(`--params 'type=event&size=200'`也予以接受。 重复 `--params` 将数值分拆为不同旗帜(`--params type=event --params size=200`; 不止一次给定的密钥是一个错误。 在查询中,一个赤裸的 `+` 被否定为模棱两可——写作 `%20` 用于空间和 `%2B` 用于加(`email=a%2Btag@b.com`),或使用JSON形式,两者都是字面的.

```bash
# List campaigns in workspace 123
cio api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'

# Get a specific campaign
cio api /v1/environments/{environment_id}/campaigns/{campaign_id} \
  --params '{"environment_id": "123", "campaign_id": "456"}'

# Create a campaign
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' \
  --json '{"campaign": {"name": "Welcome Flow", "type": "none"}}'

# Explicit method override
cio api /v1/environments/{environment_id}/campaigns/{campaign_id} -X DELETE \
  --params '{"environment_id": "123", "campaign_id": "456"}'

# Introspect endpoints
cio schema                          # list all resources
cio schema campaigns                # list endpoints for a resource
cio schema campaigns.list           # full schema for a method
cio schema GET /v1/environments/{environment_id}/campaigns  # by HTTP method + path
cio schema campaigns.list --compact # flattened one line per field instead of JSON Schema
```

### 账户ID回落

包含路径 `{account_id}` 从账户中自动填入存储的ID `cio auth login`所以,你不需要传递它 在每一个电话:

```bash
cio api /v1/accounts/{account_id}/environments
```

过 `--params '{"account_id": "..."}'` 要覆盖,或设置 `CIO_ACCESS_TOKEN` 以禁用后退(预交换的JWT可能属于不同的账户).

### 用 Jq 过滤

```bash
# Filter with --jq to save context window
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' \
  --jq '.campaigns[] | {id, name, state}'

# Complex filtering
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' \
  --jq '.campaigns[] | select(.state == "active") | {id, name}'
```

### 写入操作

```bash
# Always dry-run first
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' \
  --json '{"campaign": {"name": "Welcome Flow", "type": "none"}}' --dry-run

# Then execute (removes --dry-run)
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' \
  --json '{"campaign": {"name": "Welcome Flow", "type": "none"}}'
```

### 倾斜

```bash
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' --page 2 --limit 50

# Auto-paginate (emits NDJSON — one JSON object per line)
cio api /v1/environments/{environment_id}/campaigns \
  --params '{"environment_id": "123"}' --page-all
```

## 全球旗帜

| 旗帜 | 信封瓦尔 | 说明 |
| --- | --- | --- |
| `--token <value>` | `CIO_TOKEN` | 服务账户符号覆盖 |
| `--profile <name>` | `CIO_PROFILE` | 要使用的配置配置配置文件 |
| `-X, --method` |  | HTTP 方法覆盖( 默认: 获取, 或者如果 -- json ) |
| `--json <payload>` |  | Raw JSON 请求正文或 `@filename` 从文件读取 |
| `--params <json>` |  | 查询参数为 JSON ~ 查询字符串 |
| `--jq <expr>` |  | jq 表达式过滤器( 通过gojq) |
| `--dry-run` |  | 验证 + 打印请求, 跳过执行 |
| `--api-url <url>` |  | API 基础 URL 覆盖 |
| `--timeout <duration>` | `CIO_TIMEOUT` | HTTP 请求超时( 默认: 30s) |
| `--page <n>` |  | 页码 |
| `--limit <n>` |  | 页面大小 |
| `--page-all` |  | 自动粘贴, 释放 NDJSON |

`cio api` 重试 GET 和 HEAD 的超时程序, 并仅在请求时写入 未发送。 写入发送后未重试的回复时间 他们可能已经申请了. `--timeout` 仍然限制每次 HTTP 尝试,并且 默认为30s.

超时与 HTTP 429 共享现有的重试限制和指数回放 可重试5xx回复. `CIO_MAX_RETRIES` 默认为3次复试, 共4次 尝试; 设置为 0 以禁用这些重试 。 呼叫者取消或过期 呼叫截止时间停止重复 。 因此,重复超时的时间可能比 `--timeout` 总计。 若为 `--page-all` 它会用完复读器,会出错 ,并将任何更早的页面保留在 stdout; 呼叫者必须在退出状态之前检查其退出状态 使用输出作为完整结果.

## 退出代码

| 代码 | 含义 |
| --- | --- |
| 0 个 | 成绩 |
| 1个 | 一般错误 |
| 2个 | 校验/ 输入错误 |
| 3个 | 认证错误 |
| 页:1 | 授权错误 |
| 页:1 | API 错误( 4xx/5xx) |

## 错误格式

```json
{"error":true,"code":"AUTH_ERROR","message":"Not authenticated.","details":{"status_code":401}}
```

## 建筑

CLI使用一个 **常规 `api` 命令 + 路由注册** 结构 :

1.  `cio api <path>` ——一个使用 API 路径的单一命令 `{placeholder}` 段落
2.  OpenAPI 规格从第一次使用的活的 API 下载,并在本地缓存 `~/.cio/cache/specs/` (24h TTL,基于ETag的有条件刷新). 使用 `cio schema --refresh` 强制重新卸载.
3.  `internal/routes/enrichment.json` — OpenAPI spec中尚未注释的路由摘要,参数描述,查询参数

```bash
# Discover resources
cio schema

# List endpoints for a resource
cio schema campaigns

# Inspect a method's parameters
cio schema campaigns.list

# Make an API call
cio api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'

# CDP Pipelines (workspace_id = environment_id)
cio api /cdp/api/workspaces/{workspace_id}/sources --params '{"workspace_id": "123"}'
cio schema sources
```

## 发展

```bash
go build -o cio .
go test ./...
go test ./... -v -run TestAuthLogin
```

## 许可证

根据Apache License 2.0颁发的许可,并附有《共同条款限制》。 见 [自由主义](https://npmcn.com/package/%40customerio/cli/LICENSE)。 。 。 .

## 常见问题

### @customerio/cli 是什么？

客户首个CLI\.io APIs代理

### 如何安装 @customerio/cli？

在项目目录运行 npm install @customerio/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cio，可以用 npx cio 直接运行。

### @customerio/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/customerio\_\_cli 是否存在。

### @customerio/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @customerio/cli 可以商用吗？

@customerio/cli 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @customerio/cli 的下载量有多少？

根据 npm 官方下载统计，@customerio/cli 在 2026/10/11 – 2026/11/09 这 30 天内被下载 11,311 次，日均约 377 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @customerio/cli 还在维护吗？

最新版本 0\.0\.37 发布于 2026/11/03（8 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 42 个；首次发布于 2026/04/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。