@naturali / cli

这个 naturali 命令-每个命令一个 naturali.ai API 操作，生成自 OpenAPI规格.

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

配置

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

命令

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

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 都是同一面旗帜。

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路径，查询字符串或请求体-来自哪里 说明书，这样你就不用知道了。

值

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

文件的值

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

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

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

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

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

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

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

输出

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

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

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

{
  "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 为 管道。

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

测试

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，从不接受拉取请求。

版本控制

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

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

fix:/chore: 更改发布补丁和 feat: 从…中推断出的 压缩提交主题。每个案例都在合并时发布，打破更改 包括在内。请参阅存储库的 PIPELINE.md 和 CHANGELOG.md.