CLI、SDK 与库ant CLI

使用 CLI

ant CLI 的命令结构、输出格式、GJSON 转换、请求体和调试。

本页介绍 ant CLI 适用于所有端点的输入和输出机制。有关安装和身份验证，请参阅快速入门。有关链式命令和资源版本控制，请参阅 CLI 脚本编写与自动化。

命令结构

命令遵循 resource action 模式。嵌套资源使用冒号：

ant <resource>[:<subresource>] <action> [flags]

运行 ant --help 查看完整的资源列表，或在任何子命令后附加 --help 查看其标志。

处于 beta 阶段的资源（包括 agents、sessions、deployments、environments 和 skills）位于 beta: 前缀下。此命名空间中的命令会自动为该资源发送相应的 anthropic-beta 标头，因此您无需自行传递。仅在需要覆盖默认值时使用 --beta <header>（例如，选择使用不同的 schema 版本）。

ant models list
ant messages create --model claude-opus-5 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

全局标志

标志	描述
`--profile`	本次调用使用的命名配置文件（等同于设置 `ANTHROPIC_PROFILE`）。请参阅在工作区之间切换。
`--format`	输出格式：`auto`、`json`、`jsonl`、`yaml`、`pretty`、`raw`、`explore`
`--transform`	使用 GJSON 路径过滤或重塑响应
`-r`、`--raw-output`	打印字符串结果时不带外围引号，类似 `jq -r`
`--base-url`	覆盖 API 基础 URL
`--debug`	将完整的 HTTP 请求和响应打印到 stderr
`--format-error`、`--transform-error`	与 `--format` 和 `--transform` 相同，但应用于错误响应

输出格式

auto 会美化打印 JSON，是创建或修改资源的命令的默认格式。列表和检索命令在写入终端时默认使用交互式浏览器，在通过管道传输时默认使用美化打印的 JSON。可以使用 --format 覆盖任一默认值：

ant models retrieve --model-id claude-opus-5 --format yaml

Output

type: model
id: claude-opus-5
display_name: Claude Opus 5
created_at: "2026-07-24T00:00:00Z"
...

列表端点会自动分页。在默认格式中，每个条目会单独写出（jsonl 模式下每行一个紧凑的 JSON 对象，yaml 模式下为一系列 YAML 文档），可以顺畅地流式传输到 head、grep 和 --transform 过滤器中。

交互式浏览器

浏览器是一个用于浏览大型响应的折叠与搜索 TUI。方向键展开和折叠节点，/ 搜索，q 退出。列表和检索命令在连接到终端时默认打开它。传递 --format explore 可显式打开：

ant models list --format explore

使用 GJSON 转换输出

使用 --transform 在打印前重塑响应。表达式是一个 GJSON 路径。对于列表端点，转换会针对每个条目单独运行，而不是针对外层封装：

ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

Output

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5"}

提取标量值

要将单个字段捕获为不带引号的字符串（例如，新创建资源的 ID），请将 --transform 与 --raw-output 搭配使用。结果打印时不带 JSON 引号，可以直接赋值给 shell 变量：

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

Output

agent_011CYm1BLqPXpQRk5khsSXrs

--raw-output 与 --format raw 不同。--raw-output 会从字符串结果中去除 JSON 引号，类似 jq -r。--format raw 打印响应体的原始 JSON 字节且不自动分页；在列表端点上，它会将 --transform 应用于分页封装而不是每个条目。

传递请求体

正确的输入机制取决于数据的形态：对标量字段和简短的结构化值使用标志，对嵌套或多行请求体通过管道传入 stdin 文档，并使用 @file 引用将文件内容拉入任何字符串或二进制字段。

标志

标量字段直接映射到标志。结构化字段接受宽松的类 YAML 语法（不带引号的键、字符串可选引号）或严格的 JSON：

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"

可重复的标志会构建数组。每个 --tool 或 --event 追加一个元素：

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

通过管道将 JSON 或 YAML 文档传入 stdin 以提供完整的请求体。来自 stdin 的字段会与标志合并，标志优先。这里的 version 是先前 retrieve 返回的乐观锁令牌，而 $AGENT_ID 是按照提取标量值中的方式捕获的：

echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"

Heredoc 的工作方式相同，对于多行 YAML 很方便。给分隔符加引号（如 <<'YAML'）可禁用请求体内的变量展开。

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-5
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

文件引用

接受文件路径的标志（例如上传命令的 --file）接受裸路径：

ant beta:files upload --file ./report.pdf

要将文件内容内联到字符串值字段中，请在路径前加上 @ 前缀：

ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5}' \
  --system @./prompts/researcher.txt

在结构化标志值内部，请用引号包裹路径。要向 Messages API 发送 PDF：

ant messages create \
  --model claude-opus-5 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}' \
  --transform 'content.#(type=="text").text' --raw-output

CLI 会检测文件类型并自动将二进制文件编码为 base64。要强制使用特定编码，请对纯文本使用 @file://，对 base64 使用 @data://。使用反斜杠转义字面量的前导 @（\@username）。

调试

在任何命令中添加 --debug，即可将确切的 HTTP 请求和响应（标头和正文）打印到 stderr。API 密钥会被脱敏。

ant --debug beta:agents list

Output

GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2023-06-01
X-Api-Key: <REDACTED>
...

可用资源

CLI 公开的每个 API 资源都记录在 API 参考中。要查看本地列表，请运行 ant --help，并在任何子命令后附加 --help 查看其标志和参数。

后续步骤

CLI 脚本编写与自动化

对 API 资源进行版本控制、脚本编写模式，以及在 Claude Code 中使用

API 参考

特定端点的参数、请求字段和响应 schema

CLI 身份验证选项

API 密钥、无头主机、多个工作区和命名配置文件

Was this page helpful?

CLI、SDK 与库ant CLI

使用 CLI

ant CLI 的命令结构、输出格式、GJSON 转换、请求体和调试。

命令结构

命令遵循 resource action 模式。嵌套资源使用冒号：

ant <resource>[:<subresource>] <action> [flags]

运行 ant --help 查看完整的资源列表，或在任何子命令后附加 --help 查看其标志。

ant models list
ant messages create --model claude-opus-5 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

全局标志

标志	描述
`--profile`	本次调用使用的命名配置文件（等同于设置 `ANTHROPIC_PROFILE`）。请参阅在工作区之间切换。
`--format`	输出格式：`auto`、`json`、`jsonl`、`yaml`、`pretty`、`raw`、`explore`
`--transform`	使用 GJSON 路径过滤或重塑响应
`-r`、`--raw-output`	打印字符串结果时不带外围引号，类似 `jq -r`
`--base-url`	覆盖 API 基础 URL
`--debug`	将完整的 HTTP 请求和响应打印到 stderr
`--format-error`、`--transform-error`	与 `--format` 和 `--transform` 相同，但应用于错误响应

输出格式

ant models retrieve --model-id claude-opus-5 --format yaml

Output

type: model
id: claude-opus-5
display_name: Claude Opus 5
created_at: "2026-07-24T00:00:00Z"
...

交互式浏览器

ant models list --format explore

使用 GJSON 转换输出

使用 --transform 在打印前重塑响应。表达式是一个 GJSON 路径。对于列表端点，转换会针对每个条目单独运行，而不是针对外层封装：

ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

Output

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5"}

提取标量值

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

Output

agent_011CYm1BLqPXpQRk5khsSXrs

传递请求体

标志

标量字段直接映射到标志。结构化字段接受宽松的类 YAML 语法（不带引号的键、字符串可选引号）或严格的 JSON：

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"

可重复的标志会构建数组。每个 --tool 或 --event 追加一个元素：

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"

Heredoc 的工作方式相同，对于多行 YAML 很方便。给分隔符加引号（如 <<'YAML'）可禁用请求体内的变量展开。

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-5
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

文件引用

接受文件路径的标志（例如上传命令的 --file）接受裸路径：

ant beta:files upload --file ./report.pdf

要将文件内容内联到字符串值字段中，请在路径前加上 @ 前缀：

ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5}' \
  --system @./prompts/researcher.txt

在结构化标志值内部，请用引号包裹路径。要向 Messages API 发送 PDF：

ant messages create \
  --model claude-opus-5 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}' \
  --transform 'content.#(type=="text").text' --raw-output

调试

在任何命令中添加 --debug，即可将确切的 HTTP 请求和响应（标头和正文）打印到 stderr。API 密钥会被脱敏。

ant --debug beta:agents list

Output

GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2023-06-01
X-Api-Key: <REDACTED>
...

可用资源

CLI 公开的每个 API 资源都记录在 API 参考中。要查看本地列表，请运行 ant --help，并在任何子命令后附加 --help 查看其标志和参数。

后续步骤

CLI 脚本编写与自动化

对 API 资源进行版本控制、脚本编写模式，以及在 Claude Code 中使用

API 参考

特定端点的参数、请求字段和响应 schema

CLI 身份验证选项

API 密钥、无头主机、多个工作区和命名配置文件

Was this page helpful?

命令结构

全局标志

输出格式

交互式浏览器

使用 GJSON 转换输出

提取标量值

传递请求体

标志

Stdin

文件引用

调试

可用资源

后续步骤

命令结构

全局标志

输出格式

交互式浏览器

使用 GJSON 转换输出

提取标量值

传递请求体

标志

Stdin

文件引用

调试

可用资源

后续步骤

命令结构

全局标志

输出格式

交互式浏览器

使用 GJSON 转换输出

提取标量值

传递请求体

标志

Stdin

文件引用

调试

可用资源

后续步骤

命令结构

全局标志

输出格式

交互式浏览器

使用 GJSON 转换输出

提取标量值

传递请求体

标志

Stdin

文件引用

调试

可用资源

后续步骤