Claude Platform Docs
SDK、CLI 和库ant CLI

使用 CLI

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

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

命令结构

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

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

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

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

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

全局标志

标志描述
--profile本次调用使用的命名配置文件（等同于设置 ANTHROPIC_PROFILE）。请参阅在工作区之间切换。
--api-key-stdin从标准输入读取 API 密钥。该标志会读取全部标准输入，因此请通过标志传递请求体。
--auth-token-stdin从标准输入读取 bearer 令牌。该标志会读取全部标准输入，因此请通过标志传递请求体。
--format输出格式：auto、json、jsonl、yaml、pretty、raw、explore
--transform使用 GJSON 路径过滤或重塑响应
-r, --raw-output打印字符串结果时不带外围引号，类似 jq -r
--base-url覆盖 API 基础 URL
--workspace-id可选。作为 anthropic-workspace-id 标头发送的工作区 ID（wrkspc_...），适用于可访问多个工作区的 API 密钥（等同于设置 ANTHROPIC_WORKSPACE_ID）。请参阅选择工作区。Admin API 命令有其自己的 --workspace-id，用于指定它们所管理的工作区。
--debug将完整的 HTTP 请求和响应打印到 stderr
--format-error, --transform-error与 --format 和 --transform 相同，但应用于错误响应

输出格式

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

ant models retrieve --model-id claude-opus-5-5 --format yaml
Output
type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00: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-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5-5"}

提取标量值

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

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

传递请求体

合适的输入机制取决于数据的形态：对标量字段和简短的结构化值使用标志，对嵌套或多行的请求体通过管道传入 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-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-5
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

文件引用

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

ant files upload --file ./report.pdf

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

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

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

ant messages create \
  --model claude-opus-5-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."}
  ]}'

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: 2026-10-21
Authorization: Bearer <REDACTED>
...

可用资源

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

后续步骤

CLI 脚本编写与自动化

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

API 参考

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

CLI 身份验证选项

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

Was this page helpful?