CLI、SDK 和库ant CLI

使用 CLI

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

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

命令结构

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

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

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

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

ant models list
ant messages create --model claude-opus-4-8 --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-4-8 --format yaml

Output

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00: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-sonnet-4-6"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-4-5"}

提取标量值

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

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --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-4-8}' \
  --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-4-8
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-sonnet-4-6}' \
  --system @./prompts/researcher.txt

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

ant messages create \
  --model claude-opus-4-8 \
  --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.0.text' --raw-output

CLI 会检测文件类型并自动将二进制文件编码为 base64。要强制使用特定编码，请使用 @file:// 表示纯文本，或使用 @data:// 表示 base64。使用反斜杠转义字面量开头的 @（\@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 以查看其标志和参数。

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-4-8 --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-4-8 --format yaml

Output

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00: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-sonnet-4-6"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-4-5"}

提取标量值

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --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-4-8}' \
  --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-4-8
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-sonnet-4-6}' \
  --system @./prompts/researcher.txt

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

ant messages create \
  --model claude-opus-4-8 \
  --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.0.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 以查看其标志和参数。

Was this page helpful?