# @naturali/cli 中文文档

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

版本：0\.220\.3
npm 元数据更新时间：2026-11-01T23:09:25.360Z
中文译文更新时间：2026-11-01T23:35:10.822Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：952 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2026-07-28T22:54:09.989Z
- 最新版本发布：2026-11-01T23:09:25.164Z
- 已发布版本数：419（近 12 个月 419 个）

## 中文简介

的命令行接口。ai API，由OpenAPI规范生成

## 安装

```sh
npm install @naturali/cli
```

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

## README

# @naturali / cli

这个 `naturali` 命令-每个命令一个 [naturali.ai](https://naturali.ai/) API 操作，生成自 [OpenAPI规格](https://npmcn.com/package/api/openapi/).

```bash
pnpm add -g @naturali/cli
export NATURALI_TOKEN=nat_sk_...
```

## 配置

命令行总是与 `https://api.naturali.ai` -唯一的自然。ai API 起源，不可配置。凭证和默认项目来自 环境:

| 变量 | 目的 |
| --- | --- |
| `NATURALI_TOKEN` | 无记名证书(`nat_sk_…` 或会话JWT)。必需的。 |
| `NATURALI_PROJECT_ID` | 默认的 `--project-id` 对于需要1的命令。一个显式的 `--project-id` 还是赢了。 |

## 命令

每个操作都是一个以串命名的命令 `operationId`： `createAgent` → `create-agent`， `rotateApiKey` → `rotate-api-key`.

```bash
naturali list-commands              # every command, with its description
naturali create-agent --help        # one command's flags, and its docs link
```

标志是规范的参数名。羊肉串案例是有记录的惯例， 但是蛇形和骆驼形也是可以接受的 `--project-id`， `--project_id` 和 `--projectId` 都是同一面旗帜。

```bash
naturali list-agents --project-id proj_V1StGXR8Z5jdHi6B --limit 10

naturali create-agent \
  --project-id proj_V1StGXR8Z5jdHi6B \
  --provider-id aip_V1StGXR8Z5jdHi6B \
  --name support-triage \
  --tool-bindings '[{"tool_id":"tool_V1StGXR8Z5jdHi6B"}]'
```

标志的值去哪里- URL路径，查询字符串或请求体-来自哪里 说明书，这样你就不用知道了。

### 值

| 种类 | 如何通过考试 |
| --- | --- |
| 字符串 | `--name support-triage` |
| 数字/布尔值 | `--temperature 0.7`， `--force` (光秃秃的旗帜 `true`） |
| 对象 | `--tool-choice '{"type":"tool","name":"get_weather"}'` |
| 数组 | 重复旗子(`--capabilities a --capabilities b`)或传递一个JSON数组(`--tool-bindings '[{"tool_id":"tool_a"}]'`） |
| 从文件中 | `--content @playbook.md` （`@@` 发送一个文字前导 `@`） |

数组类型的字段总是作为列表发送，即使只有一个值。

### 文件的值

`@path` 从磁盘读取值。一个 `.yaml`， `.yml` 或者 `.json` 文件被解析， 和一个 `{ "file": "..." }` 里面被文件的内容取代， 相对于保存引用的文档已解析：

```yaml
# naturali/squad.formation.yaml
resources:
  Playbook:
    type: document
    properties:
      path: /squad/playbook.md
      content:
        file: ../intelligence/playbook.md
```

```bash
naturali validate-formation --project-id proj_V1StGXR8Z5jdHi6B \
  --template @naturali/squad.formation.yaml
```

这就是让表单模板声明文本版本化的文档的原因 在它旁边，而不是随身携带粘贴的副本。读取任何其他扩展名 作为文本而从未解析过，所以一个markdown文件以 `{` 保持字符串。

只有一个人 `{ "file": ... }` 引用是一个有其他键的对象吗 它是单独存在的，所以一个真正命名的属性 `file` 没有被劫持。

模板可以读取任何文件。读一个你以前没有写过的 部署它。

命令需要的每个路径参数都必须显式传递；一个命令 漏掉一个，失败，命名，而不是猜测。

## 输出

响应体作为格式化的JSON打印到标准输出，因此它会管道到 `jq`：

```bash
naturali list-agents --project-id proj_V1StGXR8Z5jdHi6B | jq -r '.data[].id'
```

非2xx响应将平台的错误信封打印到 **stderr** 并退出 `1`：

```json
{
  "status": 403,
  "error": { "code": "access_denied", "message": "Not your project" }
}
```

## 一代

`src/generated/routes.ts` 是构建输出——永远不要编辑它，也不要提交它。 它是由 `api/openapi/v1/*.yaml` 由 `pnpm generate`,这 `typecheck`， `test` 和 `build` 所有人先跑。看到 [`../README.md`](https://npmcn.com/package/%40naturali/README.md) 为 管道。

手写源代码仅限于分派、标志解析、凭证和帮助； 没有每个端点的代码。

## 测试

`pnpm test` 根据模拟对象运行单元套件 `fetch` -标志解析； 调度，并帮助输出，对每个拉请求。

`pnpm e2e` （`tests/e2e/smoke.ts`)是不同的：它驱动 _建_ 命令行界面 二进制(`bin/naturali`)作为实际的子流程，而不是实际部署的API， 使用一个 `NATURALI_E2E_API_KEY` account-scoped关键。它证明了一件事 嘲笑套件不能——那CLI，那 `@naturali/sdk` 它捆着，而活着 API实际上是同意的——它提供并存档了自己的一次性项目。 它需要真正的模型提供商的钱，所以它只运行作为一部分 `e2e` 工作 [`main.yml`](https://npmcn.com/package/.github/workflows/main.yml)，从不接受拉取请求。

## 版本控制

发布是自动的，版本是自动的 **与API共享 `@naturali/sdk`** -一个号码，一个git标签，三个包。 `@naturali/cli@0.28.0` 与API 0.28.0对话，并且 `naturali --help` 是从规范中生成的 发布版本是构建的基础，所以它总是你的版本可以做什么的权威。

任何改变 `api/openapi/v1/*.yaml` 重新生成此包并发布它 新的端点成为新的命令，而不需要任何人编辑命令行 改变 `@naturali/sdk`，它在构建时捆绑在一起，而不是解析 从npm。

`fix:`/`chore:` 更改发布补丁和 `feat:` 从…中推断出的 压缩提交主题。每个案例都在合并时发布，打破更改 包括在内。请参阅存储库的 [`PIPELINE.md`](https://npmcn.com/package/PIPELINE.md#5-releasing) 和 [`CHANGELOG.md`](https://npmcn.com/package/CHANGELOG.md).

## 常见问题

### @naturali/cli 是什么？

的命令行接口。ai API，由OpenAPI规范生成

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

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

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

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

### @naturali/cli 支持 ESM 还是 CommonJS？

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

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

@naturali/cli 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

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

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