# @commercelayer/agent-cli 中文文档

规范地址：https://npmcn.com/package/%40commercelayer/agent-cli/

版本：1\.0\.0-dev\.0
npm 元数据更新时间：2026-11-11T05:34:26.163Z
中文译文更新时间：2026-11-11T05:36:48.617Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40commercelayer/agent-cli
原文对照：https://npmcn.com/package/%40commercelayer/agent-cli/?lang=original
项目主页：https://commercelayer.ai/

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

- 包体积（解压后）：134 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-11-02T04:28:32.038Z
- 最新版本发布：2026-11-11T05:34:25.979Z
- 近 30 天下载量：4757（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

c11r:用于编码代理的商业地层CLI. 一个语法,c11r, 从沙盒到运行的组织.

## 安装

```sh
npm install @commercelayer/agent-cli
```

也可以使用：`pnpm add @commercelayer/agent-cli`、`yarn add @commercelayer/agent-cli`、`bun add @commercelayer/agent-cli`

## README

# c11r (韩语)

用于编码代理的商业层CLI. 从沙盒到运行中的组织 一个语法:

```
c11r <noun> <verb> [id] [--field value ...]
```

这是1.0行,在开发上 `clean-slate` 树枝。 它取代了之前的每个命令;没有保存0.x的任何命令.

## 语法

-   标准动词 : `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`。带有状态机器的名词会添加自己的动词: `c11r markets disable eu`, (中文(简体) ), `c11r orders approve 1001`, (中文(简体) ), `c11r payments capture 1001`。 。 。 .
-   普通名词在CLI中没有代码. 其字段,过滤和动词出自API的图案,并 `c11r schema <noun>` 返回这个计划.
-   旗帜是Schema的田地,在kebab或蛇的情况下: `--price-list` 财务报告和审定财务报表 `--price_list` 都一样.
-   打开 `list`, (中文(简体) ), `--<field> <value>` 以平等方式过滤 `--<field>.<op> <value>` 由另一个运算符操作: `--placed-at.gte 2026-11-01`, (中文(简体) ), `--status.in placed,approved`。 。 。 . `--waiting` 列出现在需要决定的内容.
-   一个被点标的旗帜设定对象的一部分 : `--customer.email ada@example.com`。数组需要 JSON 数组,用逗号分隔的值,或重复的旗帜;一系列对象需要 `key=value` 成对,每个旗帜一个对象: `--items sku=COFFEE,quantity=2`。 。 。 . `--data` 将字段作为 JSON 对象,或 `@` 和一个文件名.
-   数额按主要单位分列: `--amount 12.50`。 。 。 .

## 内建名词

| 命令 | 它会做什么 |
| --- | --- |
| `c11r status` | 此机器和文件夹所在位置:组织选取和从何处取出,其状态,计划,模式,限制,用途和等待什么;存储的登录,如果有的话. |
| `c11r schema <noun>` | 名词的 schema 文档:字段,过滤器,动词,其动词具有破坏性,循环可能自动化. |
| `c11r sandbox create [--name] [--seed]` | 一个匿名的沙盒 它的令牌被存储在这个机器上,从不打印;文件夹与之相连. |
| `c11r sandbox get`, (中文(简体) ), `reset`, (中文(简体) ), `claim`, (中文(简体) ), `destroy` | 沙盒的细节; 同一物物后的新组织; 人类的主张URL; 沙盒的结束. |
| `c11r loops create <name> --skill --every --allow [--max-total] [--market]` | 循环 `loops.yml`:技能,政策与节奏. 还有 `list`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete`。 。 。 . |
| `c11r loops run <name>` | 一通相传. CLI不是守护进程:排程者重复通过. |
| `c11r report sales [--from] [--to] [--by] [--interval] [--market] [--top]` | 在窗口销售, 从量子API。 平地名词:它的旗帜出自API的图谋. |
| `c11r auth login [--client-id] [--secret-file] [--keep-file]` | 人类自己的商业地层登录,来自其提供API应用. 见下文. |
| `c11r auth logout`, (中文(简体) ), `auth switch <slug> [--global]` | 忘记登录;组织命令采取行动. |

循环政策允许动词: 空动词是技能本身的名词(`approve`, (中文(简体) ), `<noun>.<verb>` 另一个管理名词在同项上的动词(`payments.capture`) (中文(简体) ). 删去或返还钱财的口号从不向政策开放.

## 登录、组织标志和秘密

二种无记. 一个 **组织标志** (单位:千美元)`sbx_...` 从 `sandbox create`, (中文(简体) ), `org_...` 从 `organizations create` 财务报告和审定财务报表 `organizations connect`根据一个组织的数据采取行动。 这个 **登录** 是人类自己提供的API应用程序,用于 `organizations`, (中文(简体) ), `members`, (中文(简体) ), `roles` 编辑 `credentials` 被索赔的组织。 每个动词的用法都说它需要什么`verbs[].credential`),而CLI发送这一个.

`c11r auth login` 读取客户身份和客户秘密:

-   在终端中,在提示时键入;该密钥不重复;
-   没有终端, 从文件中 : `--secret-file <path>`,或默认 `~/.config/c11r/provisioning.secret`。文件持有 `client_id=...` 财务报告和审定财务报表 `client_secret=...` 线条(或带有这些密钥的JSON,或单独的秘密,与 `--client-id`. c11r 只有在没有其他用户能够读取时才读取(模式600),删除一次读取,除非 `--keep-file` 提供;
-   没有终端也没有文件,它立刻停止 `secret_required`, (中文(简体) ), `next_step.action` `human_step` 和仪表板页面 `next_step.url`,并将文件,模式600作为人类完成的两行: `client_id=` 财务报告和审定财务报表 `client_secret=`。一个缺少两个值的文件得到相同的答案,没有被发送到商业层。 礛 `c11r auth login` 读它.

从来没有从一面旗帜或环境。 c11r在Commercial Layer交换了对子两个小时的代币,只将该代币发送给了c11r API;客户端的秘密从不离开这台机器. 两人都留在 `credentials.json`,模式 600,并且从未打印. `c11r status` 显示存储的登录为 `cli.login`, (中文(简体) ), `{ client_id, email, stored_at }`,或无:读于此机上,从来秘诀. `auth logout` 忘记登录; 其最后一个标志在两个小时内自行结束 。 组织标志留下.

`organizations create` 财务报告和审定财务报表 `organizations connect <slug>` 一次回答组织符号: 它像沙盒符号一样被存储. `connect --revoke-others` 并请求确认。 在一个登录且没有组织标志的组织名称下,一个组织的名词就停止了 `no_credentials` 和下一步 `c11r organizations connect <slug>`。 。 。 . `members` 财务报告和审定财务报表 `roles` 有组织标志的,没有登入该标志的,API说需要什么:一个沙盒的索赔,一个声称的组织登录. `organizations` 没有登录在此停留 `login_required`。 。 。 .

`credentials create` 财务报告和审定财务报表 `credentials token` 回答一个秘密一次。 c11r 将其写入一个有模式 600 的文件, 并打印文件、 格式和提示, 永远不显示值: 默认 `~/.config/c11r/secrets/<org>/<name>.env` (单位:千美元)`<id>-token.env` 或 `--out <path>`,作为 `KEY=value` 线条或带 `--format json` 一个JSON对象。 文件在请求发送前被检查; 只有一个已经替换到 `--yes`。一个 git 仓库内不忽略的文件会得到警告 `secret_not_ignored`与 `--dry-run` 什么都没有写 `secret_file` 说它会去哪里. `credentials delete` 删除 c11r 为证书在 `~/.config/c11r/secrets/<org>/` 并将他们列入其中 `removed_files`· ; `sandbox destroy` 删除该组织的整个文件夹并将其命名于 `forgotten.secrets`。所写文件 `--out` 没有跟踪和停留:警告 `out_files_not_tracked` 因此,当这个组织的秘密被写进 `--out` 中,或当一个删除找不到要删除的东西时。 一个符号文件携带 `CL_BASE_ENDPOINT` 除了标志. `sales-calls book` 一次回答取消符号: 保存在 `credentials.json` 财务报告和审定财务报表 `sales-calls cancel <booking>` 发送它.

## 全球旗帜

| 旗帜 | 它会做什么 |
| --- | --- |
| `--json` | JSON输出. 默认和唯一的格式 . |
| `--dry-run` | 写下来,CLI会用 `?dry_run=true`:API检查所有情况(国家,计划,限制,商业层的现状)并回答它会做什么, `would: [...]`,没有写。 无需确认。 阅读忽略了它. |
| `--yes` | 预先确认一个破坏性动词. |
| `--org <slug>` | 组织将采取行动, 以其储存的标志. |
| `--live` | 索赔组织实况数据: `?mode=live` 每一个请求。 没有它,测试模式. |
| `--help` | 描述它所遵循的名词或动词,从它的用法. |

破坏性动词(删除, `orders cancel`, (中文(简体) ), `payments void` 财务报告和审定财务报表 `refund`, (中文(简体) ), `sandbox reset` 财务报告和审定财务报表 `destroy`() 在终端中请求确认,然后发送 `confirm=true`。没有终端,例如当代理或调度运行CLI时,他们就永远不会等待:没有 `--yes` 他们马上停下来 `confirmation_required` 和退出代码3.

## 哪个组织

`--org`,则 `C11R_ORG`,则 `.c11r.json` 在项目文件夹中( 通过走起, 如 `.git`),然后设置默认值 `auth switch --global`,然后存储的组织,确切的保存一个(绝不是登录名词) `?org=`) (中文(简体) ). 数个存储,没有命名,命令停止 `org_required` 并列出他们.

-   托肯斯只出现在 `~/.config/c11r/credentials.json` (或低于 `XDG_CONFIG_HOME`),模式600. CLI从不打印一个,只是它的提示.
-   `.c11r.json` 仅持有 `{ "org": "<slug>" }`:没有秘密,安全可犯. `sandbox create`, (中文(简体) ), `organizations create` 财务报告和审定财务报表 `auth switch` 写下来 `organizations connect` 当文件夹没有链接时; `reset` 随从新的子弹; `destroy` 当它命名被摧毁的组织时删除它.
-   项目文件夹是一个 `.c11r.json`,否则与 `store.yml` 或者说 `loops.yml`,否则就是现在的. `loops.yml` 去那边.

## 输出、出错和退出代码

每个答案都是一个JSON对象 在Stdout上,API的信封:

```json
{ "data": {}, "state": { "lifecycle": "sandbox", "plan": null, "mode": "test", "org": "zztest-blue-beans", "expires_at": "2026-11-17T00:00:00Z" }, "warnings": [], "next": [] }
```

CLI自己的答案 (帮助, rops.yml) 形状相同, 有 `state` 无效。 每个错误,API的或CLI的,是:

```json
{
  "error": {
    "code": "state_required",
    "message": "Live mode needs a claimed organization; this is a sandbox.",
    "required_state": "claimed",
    "required_plan": null,
    "missing": null,
    "path": null,
    "next_step": { "action": "claim", "command": "c11r sandbox claim", "url": null }
  },
  "state": { "lifecycle": "sandbox", "plan": null, "mode": "test", "org": "zztest-blue-beans", "expires_at": "2026-11-17T00:00:00Z" }
}
```

`code` 稳定. `missing` 实值 `{ noun, why }`, (中文(简体) ), `path` 旗子或球场有过失, `next_step.action` 一个 `create_sandbox`, (中文(简体) ), `claim`, (中文(简体) ), `upgrade`, (中文(简体) ), `contact_sales`, (中文(简体) ), `create_dependency`, (中文(简体) ), `fix_request`, (中文(简体) ), `retry_later`, (中文(简体) ), `human_step`, (中文(简体) ), `none`。 。 。 . `human_step` 只有人类能做的 比如把一个秘密保存到一个文件里 写着一个网页 `url` 当有一个。 CLI 可添加 `did_you_mean` 财务报告和审定财务报表 `details`。 。 。 .

| 退出 | 含义 | 代码 |
| --- | --- | --- |
| 0 个 | 已执行 |  |
| 1个 | 出人意料的失败: c11r 有错误, 或 API 回答后磁盘被拒绝的秘密 | `secret_not_written` |
| 2个 | 命令无效 | `unknown_noun`, (中文(简体) ), `unknown_verb`, (中文(简体) ), `unknown_field`, (中文(简体) ), `invalid_value`, (中文(简体) ), `missing_value`, (中文(简体) ), `missing_argument`, (中文(简体) ), `missing_id`, (中文(简体) ), `unexpected_argument`, (中文(简体) ), `no_fields`, (中文(简体) ), `org_required`, (中文(简体) ), `invalid_config`, (中文(简体) ), `secret_required`, (中文(简体) ), `insecure_file` |
| 3个 | 破坏性动词需要确认 | `confirmation_required`, (中文(简体) ), `confirmation_declined` |
| 页:1 | 该组织需要另一个国家或计划,或已经到期,或达到极限 | `state_required`, (中文(简体) ), `plan_required`, (中文(简体) ), `expired`, (中文(简体) ), `limit_reached` |
| 页:1 | 无此类资源 | `not_found`, (中文(简体) ), `claim_not_found` |
| 6个 | aPI或商业层拒绝了请求 | `invalid_argument`, (中文(简体) ), `invalid_transition`, (中文(简体) ), `conflict`, (中文(简体) ), `dependency_missing`, (中文(简体) ), `commercelayer_refused`, (中文(简体) ), `policy_forbidden`, (中文(简体) ), `not_supported`, (中文(简体) ), `forbidden` |
| 第7条 | aPI 没有回答, 忙, 或失败 | `api_unreachable`, (中文(简体) ), `rate_limited`, (中文(简体) ), `commercelayer_busy`, (中文(简体) ), `commercelayer_unavailable`, (中文(简体) ), `api_error`, (中文(简体) ), `schema_unavailable`, (中文(简体) ), `invalid_response` |
| 第8条 | 错误或被撤销的指使,没有为被命名的组织存储指使,或没有登录 | `unauthorized`, (中文(简体) ), `no_credentials`, (中文(简体) ), `login_required` |

`rate_limited` 读取和写作 : 没有处理. `commercelayer_busy` 财务报告和审定财务报表 `commercelayer_unavailable` 重审后只读;可能已经到达商业层的书写在下一步失败。 唯一的例外是 `sandbox create`: 它发出新鲜的 `Idempotency-Key`,在5xx或丢失的连接后,它会用相同的密钥重复创建,所以API会回答它制作的沙盒并存储它的令牌. 每次重试只要API说`retry_after` 错误中的秒,或 `Retry-After` 头,最多30秒;没有它,1到3秒。 当API要求超过30秒时, CLI 不等待: 错误转到代理, 与 `retry_after`计划好了 每次重试都会写出一行到 Stderr.

## 环境

| 变量 | 它会做什么 |
| --- | --- |
| `C11R_API_URL` | API的基础URL, `https://api.commercelayer.ai/v1` 默认; `http://localhost:8787/v1` 为wragler dev。 没有 URL `/v1` 懂了吗. |
| `C11R_ORG` | 该组织,何时 `--org` 未给出. |
| `C11R_TOKEN` | 组织代号,现在使用, 任何存储的:为CI. |
| `C11R_PROVISIONING_TOKEN` | 即时登录符,用于: CI. 从来不是客户的秘密. |
| `C11R_AUTH_URL` | 商业层的标志性终点, `https://auth.commercelayer.io/oauth/token` 默认:用于测试. |
| `C11R_TEST` | `1` 将沙盒标为测试组织, 如名称开始 `zztest`。 。 。 . |
| `C11R_SCHEMA_CACHE` | `0` 关闭10分钟的缓存 `~/.cache/c11r`。 。 。 . |
| `C11R_RETRY_CAP_S` | 最长的CLI等待一次重试,默认为30. |
| `C11R_TIMEOUT_MS` | 一个请求需要多长时间, 默认需要30000( 沙盒创建等待更长) . |

## 常见问题

### @commercelayer/agent-cli 是什么？

c11r:用于编码代理的商业地层CLI\. 一个语法,c11r, 从沙盒到运行的组织\.

### 如何安装 @commercelayer/agent-cli？

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

### @commercelayer/agent-cli 支持 TypeScript 吗？

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

### @commercelayer/agent-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

### @commercelayer/agent-cli 可以商用吗？

@commercelayer/agent-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @commercelayer/agent-cli 的下载量有多少？

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

### @commercelayer/agent-cli 还在维护吗？

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