CLI

使用 ant 命令行工具直接从终端与 Claude API 交互

ant CLI 提供从终端访问 Claude API 的能力。每个 API 资源都暴露为子命令，支持输出格式化、响应过滤，以及 YAML 或 JSON 文件输入，使其适用于交互式探索和自动化场景。

与使用 curl 调用 API 相比，ant 允许你通过类型化标志或管道输入的 YAML 来构建请求体，而不是手写 JSON；可以通过 @path 引用将文件内容内联到字符串字段中；并使用内置的 --transform 查询从响应中提取字段（无需额外的 JSON 工具）。列表端点会自动分页。Claude Code 原生支持使用 ant。

安装

brew install anthropics/tap/ant

VERSION=1.9.1
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

go install github.com/anthropics/anthropic-cli/cmd/ant@latest

export PATH="$PATH:$(go env GOPATH)/bin"

检查安装：

ant --version

认证

交互式登录

ant auth login 允许你在不创建或管理 API 密钥的情况下调用 API。它会打开一个基于浏览器的 OAuth 流程连接到 Claude 控制台，并将获取的凭据存储在 $ANTHROPIC_CONFIG_DIR 下（有关操作系统特定的默认值，请参阅配置目录）。在远程主机或没有本地浏览器的环境中，传入 --no-browser 以打印授权 URL，并将返回的代码粘贴回终端。

ant auth login

# 在没有浏览器的远程主机上：
ant auth login --no-browser

# 绑定到特定工作区并跳过浏览器选择器：
ant auth login --workspace-id wrkspc_01...

# 如果通过 --profile 传入的命名配置文件不存在，
# 将使用该名称创建一个新的命名配置文件。
ant auth login --profile <profile-name>

在浏览器流程中，你需要选择一个组织，然后选择一个工作区。颁发的令牌限定于该工作区，因此 CLI 只能看到属于该工作区的资源。传入 --workspace-id 可直接绑定并跳过选择器。要在多个工作区中工作，请参阅切换工作区。

交互式登录适用于在本地机器上进行本地开发和脚本编写。对于 CI、服务器和容器等非交互式工作负载，请使用 Workload Identity Federation。

登录会将凭据写入 credentials/.json。配置文件的首次登录还会创建 configs/.json 并将其设置为活动配置文件。要删除存储的凭据，请运行 ant auth logout，或运行 ant auth logout --all 以清除所有配置文件。

API 密钥

CLI 也会从 ANTHROPIC_API_KEY 环境变量读取你的 API 密钥。从 Claude 控制台 获取密钥。

echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.bashrc
source ~/.bashrc

setx ANTHROPIC_API_KEY "sk-ant-api03-..."

要为单次调用覆盖密钥，请传入 --api-key。要指向不同的 API 主机，请设置 ANTHROPIC_BASE_URL 或传入 --base-url。

检查认证状态

ant auth status 打印 CLI 选择的凭据来源（API 密钥环境变量、OAuth 登录、联合身份或配置文件）、活动配置文件、活动令牌绑定的工作区以及配置目录路径。使用它来诊断工作负载为何选择了错误的凭据或工作区。

ant auth status

Active profile:  default
Config dir:      ~/.config/anthropic
Profile config:  ~/.config/anthropic/configs/default.json
Credentials:     ~/.config/anthropic/credentials/default.json

Credentials
  (active) * Profile (user_oauth) [via active_config]       sk-ant-oat01-EXA...
...

Workspace
  (active) * Workspace                                      wrkspc_01... (Engineering)

读取 (active) 行以查看哪个凭据来源和工作区生效。该命令报告状态而非执行健康检查，因此不要针对退出状态编写脚本。有关凭据来源的完整排序，请参阅凭据优先级。

切换工作区

交互式登录令牌绑定到单个工作区。要对多个工作区使用 CLI，请在各自的命名配置文件下登录每个工作区，然后在它们之间切换：

export ANTHROPIC_CONFIG_DIR="$PWD/antconfig"
mkdir -p "$ANTHROPIC_CONFIG_DIR/configs"
printf '{"authentication":{"type":"user_oauth"}}' > "$ANTHROPIC_CONFIG_DIR/configs/other-ws.json"
# 1. 创建配置文件（交互式；在浏览器中选择另一个工作区，
#    或传入 --workspace-id 跳过选择器）：
# ant auth login --profile other-ws

# 2. 将其设为后续命令的默认配置文件：
ant profile activate other-ws

# 3. 或者为单个命令选择它而不更改默认值：
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

运行 ant auth status 以确认当前活动的配置文件和工作区。

管理配置文件

ant profile 子命令用于直接检查和编辑配置文件状态：

export ANTHROPIC_CONFIG_DIR="$PWD/antconfig"
mkdir -p "$ANTHROPIC_CONFIG_DIR/configs"
printf '{"authentication":{"type":"user_oauth"}}' > "$ANTHROPIC_CONFIG_DIR/configs/other-ws.json"
ant profile list
ant profile get --profile other-ws
ant profile set workspace_id wrkspc_01... --profile other-ws

ant profile set 的可写键包括 workspace_id、base_url、organization_id、scope、client_id 和 console_url。设置 workspace_id 会在配置文件配置中记录目标工作区，但不会重新绑定已颁发的凭据；请在该配置文件下再次运行 ant auth login 以获取新工作区的令牌。

有关配置文件模式和联合身份块，请参阅配置文件配置文件。有关 Workload Identity Federation，请参阅认证概述和 WIF 参考。

发送第一个请求

安装并认证二进制文件后，调用 Messages API：

ant messages create \
  --model claude-opus-4-7 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

{
  "model": "claude-opus-4-7",
  "id": "msg_01YMmR5XodC5nTqMxLZMKaq6",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How are you doing today? Is there something I can help you with?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 27, "output_tokens": 20 /*, ... */ }
}

响应是完整的 API 对象，因为 stdout 是终端所以会格式化输出。本页面的其余部分介绍如何重塑输出、传递复杂的请求体以及将命令链接在一起。

命令结构

命令遵循 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-7 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

全局标志

输出格式

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

ant models retrieve --model-id claude-opus-4-7 --format yaml

type: model
id: claude-opus-4-7
display_name: Claude Opus 4.7
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

{"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"

agent_011CYm1BLqPXpQRk5khsSXrs

传递请求体

正确的输入机制取决于数据的形状：对标量字段和短结构化值使用标志，对嵌套或多行请求体使用管道 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-7}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

标准输入

通过管道将 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-7
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-7 \
  --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）。

API 资源的版本控制

你可以使用 CLI 将 API 资源（如 skills、agents、environments 或 deployments）作为 YAML 文件进行版本控制，并与 Claude API 保持同步。

1. 定义你的 agent

   将 agent 定义写入 summarizer.agent.yaml：

   name: Summarizer
   model: claude-sonnet-4-6
   system: |
     You are a helpful assistant that writes concise summaries.
   tools:
     - type: agent_toolset_20260401
   

2. 创建 agent

   ant beta:agents create < summarizer.agent.yaml
   

   {
     "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
     "version": 1,
     "name": "Summarizer",
     "model": "claude-sonnet-4-6"
     /* ... */
   }
   

   记下响应中的 id。你将在后续步骤中将其传递给 session 创建命令。

   💡

   Tip

   将 summarizer.agent.yaml 提交到你的仓库，并在 CI 流水线中与 API 保持同步。更新命令需要 agent ID 和当前版本作为标志：

   ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
   

3. 定义环境

   Session 运行在环境中，环境定义了它执行的容器。将环境定义写入 summarizer.environment.yaml：

   name: summarizer-env
   config:
     type: cloud
     networking:
       type: unrestricted
   

4. 创建环境

   ant beta:environments create < summarizer.environment.yaml
   

   {
     "id": "env_01595EKxaaTTGwwY3kyXdtbs",
     "name": "summarizer-env"
     /* ... */
   }
   

   记下响应中的 id。你将在后续步骤中将其传递给 session 创建命令。

   💡

   Tip

   将 summarizer.environment.yaml 提交到你的仓库，并在 CI 流水线中与 API 保持同步。更新命令需要环境 ID 作为标志：

   ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml
   

5. 启动 session

   将前面输出中的 agent id 和环境 id 粘贴到 session 创建命令中：

   ant beta:sessions create \
     --agent agent_011CYm1BLqPXpQRk5khsSXrs \
     --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
     --title "Summarization task"
   

   {
     "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
     "status": "running"
     /* ... */
   }
   

6. 发送用户消息

   将前面输出中的 session id 复制到 --session-id 中：

   ant beta:sessions:events send \
     --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
     --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'
   

7. 读取对话

   --transform 针对列出的每个事件运行，因此会按顺序打印每条消息的文本。--format auto 覆盖列表命令在终端中默认打开的交互式浏览器：

   ant beta:sessions:events list \
     --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
     --transform 'content.0.text' --format auto --raw-output
   

   Summarize the benefits of type safety in one sentence.
   Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.
   

   💡

   Tip

   要在 session 运行时监视它，请使用 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K。事件在到达时写入 stdout。

脚本编写模式

CLI 设计为可与标准 shell 工具组合使用。

将列表输出链接到第二个命令

在列表端点上使用 --transform id --raw-output 每行输出一个裸 ID，因此 head 和 xargs 等标准工具可以直接使用。捕获第一个结果，然后将其传递给后续命令：

FIRST_AGENT=$(ant beta:agents list \
  --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl

检查错误

--transform-error 和 --format-error 标志对错误响应应用相同的过滤。--raw-output 不适用于错误，因此使用 --format-error yaml 获取不带引号的标量。仅提取错误消息：

ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1

GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.

从 Claude Code 使用 CLI

Claude Code 开箱即用地了解如何使用 ant CLI。安装并认证 CLI 后，你可以直接让 Claude Code 操作你的 API 资源。例如：

• "列出我最近的 agent sessions 并总结哪些出现了错误。"
• "将 ./reports 中的所有 PDF 上传到 Files API 并打印结果 ID。"
• "获取 session session_01... 的事件并告诉我 agent 在哪里卡住了。"

Claude Code 会调用 ant，解析结构化输出，并对结果进行推理（无需自定义集成代码）。

调试

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

ant --debug beta:agents list

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>
...

Shell 补全

CLI 附带 bash、zsh、fish 和 PowerShell 的补全脚本。为你的 shell 生成并安装：

ant @completion zsh > "${fpath[1]}/_ant"
# 重启 shell 或运行：autoload -U compinit && compinit

ant @completion bash > /etc/bash_completion.d/ant

ant @completion fish > ~/.config/fish/completions/ant.fish

ant @completion powershell | Out-String | Invoke-Expression
# 要在会话之间持久化：
# ant @completion powershell >> $PROFILE

可用资源

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