# CLI

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

---

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

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

<Info>
有关特定端点的参数和响应模式，请参阅 [API 参考](/docs/en/api/cli/messages/create)。本页面介绍适用于所有端点的 CLI 特定功能和工作流程。
</Info>

## 安装

<Tabs>
<Tab title="Homebrew (macOS)">

```bash
brew install anthropics/tap/ant
```

</Tab>
<Tab title="curl (Linux/WSL)">

对于 Linux 环境，直接下载发布二进制文件。

```bash nocheck
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
```

你可以在 [GitHub 发布页面](https://github.com/anthropics/anthropic-cli/releases) 找到所有版本。

</Tab>
<Tab title="Go">

你也可以使用 `go install` 从源代码安装 CLI。需要 Go 1.22 或更高版本。

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

二进制文件将放置在 `$(go env GOPATH)/bin` 目录中。如果该目录不在你的 `PATH` 中，请添加：

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

</Tab>
</Tabs>

检查安装：

```bash
ant --version
```

## 认证

### 交互式登录

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

```bash CLI nocheck
ant auth login

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

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

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

在浏览器流程中，你需要选择一个组织，然后选择一个[工作区](/docs/en/manage-claude/workspaces)。颁发的令牌[限定于该工作区](/docs/en/manage-claude/workspaces#api-keys-and-resource-scoping)，因此 CLI 只能看到属于该工作区的资源。传入 `--workspace-id` 可直接绑定并跳过选择器。要在多个工作区中工作，请参阅[切换工作区](#switch-between-workspaces)。

交互式登录适用于在本地机器上进行本地开发和脚本编写。对于 CI、服务器和容器等非交互式工作负载，请使用 [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation)。

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

### API 密钥

CLI 也会从 `ANTHROPIC_API_KEY` 环境变量读取你的 API 密钥。从 [Claude 控制台](https://platform.claude.com/settings/keys) 获取密钥。

<Tabs>
<Tab title="zsh">

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

</Tab>
<Tab title="bash">

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

</Tab>
<Tab title="Windows">

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

打开新终端以使更改生效。

</Tab>
</Tabs>

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

### 检查认证状态

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

```bash CLI nocheck
ant auth status
```

```text
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)` 行以查看哪个凭据来源和工作区生效。该命令报告状态而非执行健康检查，因此不要针对退出状态编写脚本。有关凭据来源的完整排序，请参阅[凭据优先级](/docs/en/manage-claude/wif-reference#credential-precedence)。

### 切换工作区

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

```bash CLI hidelines={1..3}
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`](#check-authentication-status) 以确认当前活动的配置文件和工作区。

<Note>
仅在未设置 API 密钥时才会检查配置文件。如果你的环境中存在 `ANTHROPIC_API_KEY`，它将覆盖所有配置文件，这些命令都将使用该密钥限定的工作区。在切换配置文件之前请取消设置它。
</Note>

### 管理配置文件

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

```bash CLI hidelines={1..3}
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` 以获取新工作区的令牌。

有关配置文件模式和联合身份块，请参阅[配置文件配置文件](/docs/en/manage-claude/wif-reference#profile-configuration-file)。有关 Workload Identity Federation，请参阅[认证概述](/docs/en/manage-claude/authentication)和 [WIF 参考](/docs/en/manage-claude/wif-reference)。

## 发送第一个请求

安装并认证二进制文件后，调用 [Messages API](/docs/en/api/cli/messages/create)：

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

```json Output
{
  "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` 模式。嵌套资源使用冒号：

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

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

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

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

### 全局标志

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

## 输出格式

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

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

```yaml Output
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` 以显式打开：

```bash
ant models list --format explore
```

## 使用 GJSON 转换输出

使用 `--transform` 在打印前重塑响应。表达式是 [GJSON 路径](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)。对于列表端点，转换针对每个项目单独运行，而非整个信封：

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

```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 变量：

```bash
AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"
```

```text Output
agent_011CYm1BLqPXpQRk5khsSXrs
```

<Note>
`--raw-output` 与 `--format raw` 不同。`--raw-output` 去除字符串结果的 JSON 引号，类似 `jq -r`。`--format raw` 打印响应体的原始 JSON 字节而不自动分页；在列表端点上，它将 `--transform` 应用于分页信封而非每个项目。
</Note>

## 传递请求体

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

### 标志

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

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

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

```bash
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` 按照[提取标量值](#extract-a-scalar)中的方式捕获：

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

Heredoc 的工作方式相同，适合多行 YAML。引用分隔符（如 `<<'YAML'`）以禁用正文内的变量展开。

```bash
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`，接受裸路径：

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

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

```bash
ant beta:agents create \
  --name "Researcher" --model '{id: claude-sonnet-4-6}' \
  --system @./prompts/researcher.txt
```

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

```bash
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 保持同步。

<Note>
有关这些资源的更多信息，请参阅 [Managed Agents](/docs/en/managed-agents/overview)。
</Note>

<Steps>
<Step title="定义你的 agent">

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

```yaml 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
```

</Step>
<Step title="创建 agent">

```bash
ant beta:agents create < summarizer.agent.yaml
```

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

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

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

```bash CLI nocheck
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
```
</Tip>

</Step>
<Step title="定义环境">

Session 运行在[环境](/docs/en/api/cli/beta/environments)中，环境定义了它执行的容器。将环境定义写入 `summarizer.environment.yaml`：

```yaml summarizer.environment.yaml
name: summarizer-env
config:
  type: cloud
  networking:
    type: unrestricted
```

</Step>
<Step title="创建环境">

```bash
ant beta:environments create < summarizer.environment.yaml
```

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

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

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

```bash CLI nocheck
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml
```
</Tip>

</Step>
<Step title="启动 session">

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

```bash highlight={2..3}
ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"
```

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

</Step>
<Step title="发送用户消息">

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

```bash highlight={2}
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."}]}'
```

</Step>
<Step title="读取对话">

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

```bash highlight={2}
ant beta:sessions:events list \
  --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
  --transform 'content.0.text' --format auto --raw-output
```

```text 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。
</Tip>

</Step>
</Steps>

## 脚本编写模式

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

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

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

```bash
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` 获取不带引号的标量。仅提取错误消息：

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

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

## 从 Claude Code 使用 CLI

[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) 开箱即用地了解如何使用 `ant` CLI。安装并认证 CLI 后，你可以直接让 Claude Code 操作你的 API 资源。例如：

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

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

## 调试

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

```bash
ant --debug beta:agents list
```

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

## Shell 补全

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

<Tabs>
<Tab title="zsh">

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

</Tab>
<Tab title="bash">

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

</Tab>
<Tab title="fish">

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

</Tab>
<Tab title="PowerShell">

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

</Tab>
</Tabs>

## 可用资源

CLI 暴露的每个 API 资源都记录在 [API 参考](/docs/en/api/cli/messages/create) 中。要获取本地列表，请运行 `ant --help`，在任何子命令后附加 `--help` 查看其标志和参数。