Claude Platform ant CLI：官方开发者指南

发布内容

简而言之： Claude Platform 现已推出官方 API CLI，名为 antant。它将 Claude API 端点转换为终端命令，支持结构化输入，能够格式化和过滤输出，并为 Claude Code 提供了一种在 Claude Platform 资源上进行操作的原生方式。

这条发布推文很有参考价值，因为它说明了该产品的用途：API 调用、Managed Agents、shell 管道和编码智能体。官方 CLI 文档补充了具体机制：OAuth 登录、API keys、工作区配置、YAML 和 JSON 请求体、GJSON 转换、自动分页、调试输出、shell 自动补全以及资源帮助。

The new workflow shape:

terminal command
  -> ant resource action
  -> Claude API endpoint
  -> structured JSON/YAML/raw output
  -> shell pipeline, CI step, or Claude Code agent

一句话定义

ant ant CLI is Anthropic's command-line interface for calling Claude API resources from a terminal.它并非 Python 或 TypeScript SDK 的替代品。它是一个 shell 原生界面，用于探索端点、编写 API 资源脚本、传输输出，并让 Claude Code 无需自定义集成代码即可检查平台状态。

心智模型：四个部分

读取 ant 作为 shell 工作流与 Claude Platform 之间的小型适配器。官方文档在 Messages、beta 资源、输出转换和 Claude Code 使用方面重复了相同的模式。

[credentials/profile]
        |
        v
[ant resource:subresource action] --flags < stdin.yaml
        |
        v
[Claude API resource]
        |
        v
[formatted output] --transform -> shell, CI, or Claude Code

• 凭据： OAuth 登录、API key、联合身份验证或命名配置文件。
• 命令： a resource action 模式，嵌套资源以冒号分隔。
• 输入： 标志（flags）、stdin YAML/JSON 以及 @file 内联文件内容的引用。
• 输出： 格式化的 JSON、YAML、JSONL、原始输出、交互式资源管理器以及 GJSON 转换。

安装与验证

The CLI docs show install paths for Homebrew on macOS, curl on Linux/WSL, and Go. The least ambiguous official commands are Homebrew and Go, followed by the version check:

# macOS
brew install anthropics/tap/ant

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

# Verify
ant --version

文档还指出，每个公开的 API 资源都会出现在本地帮助输出中。对于新安装，请运行 ant --help，然后将 --help 附加到你计划使用的资源后，例如 ant messages create --help。

身份验证：OAuth、API Keys 和配置文件

官方文档将身份验证分为本地开发和非交互式工作负载。对于开发人员机器， ant auth login 开启一个基于浏览器的 OAuth 流程以连接到 Claude Console。对于没有本地浏览器的远程主机， --no-browser 标志会打印出一个授权 URL，并要求您粘贴返回的代码。

ant auth login
ant auth login --no-browser
ant auth login --workspace-id wrkspc_01...
ant auth login --profile platform-dev

ant auth status
ant auth logout
ant auth logout --all

关于工作区的重要细节：在 OAuth 登录期间，您需要选择一个组织和工作区。令牌的作用域仅限于该工作区。若要跨多个工作区工作，请为每个工作区创建一个配置文件，并显式切换配置文件。

ant auth login --profile other-ws
ant profile activate other-ws

ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

对于 CI、容器和服务器，CLI 文档建议不要使用交互式登录，而应使用 Workload Identity Federation（工作负载身份联合）。这使得安装后的规则保持清晰：本地机器使用 OAuth，自动化流程使用联合身份，而当您明确需要基于密钥的身份验证时，则使用 API keys。

最小端到端请求

一旦 ant 完成安装并完成身份验证，文档便会从 Messages API 开始介绍。这是最基本的结构：模型、最大 token 数以及用户消息。

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

文档将响应显示为完整的 API 对象：模型 ID、消息 ID、助手角色、内容数组、停止原因和使用情况。当 stdout 为终端时，CLI 会对该对象进行美化打印。

命令结构

命令遵循 resource action 结构。嵌套资源使用冒号，而 beta 资源位于 beta:下。文档将 agents、sessions、deployments、environments 和 skills 列为 beta 资源。

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

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

beta 前缀非常重要，因为这些命令会自动为该资源发送相应的 anthropic-beta 标头。文档建议仅在需要覆盖默认架构版本时才使用 --beta。

输出格式与 GJSON 转换

输出是关于 ant 不仅仅是围绕 curl的便捷封装。 auto文档中列出了 jsonAntigravity jsonlGemini yamlChrome prettyMCP rawAgent-First exploreIDE，以及 API。列表端点支持自动分页，且列表输出可以整洁地流式传输到 shell 命令中。

转换语言为 GJSON。对于列表端点，转换是针对每一项而非整个数据包执行的。这就是为什么这种模式可以每行打印一个 Agent 摘要：

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

我的实践建议：当下一个命令是 shell 工具时使用 --format jsonl ，而当你需要为下一个命令获取资源 ID 时使用 --transform id --raw-output 。 ant 调用。

无需手写 JSON 即可传递请求体

CLI 文档描述了三种输入模式：flags、stdin 和文件引用。标量字段映射到 flags。结构化字段接受宽松的 YAML 风格语法或严格的 JSON。完整的请求体可以通过 stdin 以 JSON 或 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

对于文件内容，文档使用了 @path。这允许你将提示词文件内联到一个字符串字段中，或者将 PDF 发送到 Messages API，CLI 会自动检测并对二进制文件进行 base64 编码。

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

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

版本控制 API 资源

对于平台团队来说，最重要的发布细节并非那一行 Messages 调用，而是关于将 API 资源保存在 YAML 文件中的文档部分。该示例涵盖了 Managed 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

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

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

ant beta:environments create < summarizer.environment.yaml

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

这种模式将平台资源转化为你可以审查、存储在仓库中并从 CI 进行更新的文件。CLI 并未消除对治理的需求，但它使操作对象模型对 shell 脚本可见。

在 Claude Code 中使用 ant

发布推文称 ant 已被编码智能体充分理解，且 CLI 文档明确了 Claude Code 的行为：安装并验证 ant 后，Claude Code 可以调用它，解析结构化输出，并对结果进行推理。

Prompts the docs say are now reasonable:

"List my recent agent sessions and summarize which ones errored."
"Upload every PDF in ./reports to the Files API and print the resulting IDs."
"Pull the events for session session_01... and tell me where the agent got stuck."

实际意义在于：Claude Code 不再需要定制脚本来理解许多 Claude Platform 资源。安装 ant并将其验证到正确的 workspace，Claude Code 就能获得一个可用的结构化命令界面。

我在阅读发布内容时犯的错误

我的第一个错误假设是 ant 仅仅是一个更美观的 Messages API 封装。文档明确了其更广泛的目标：API 资源操作、beta Managed Agents、环境、会话、文件、配置文件、转换以及 Claude Code 移交。

第二个错误假设是配置文件切换总是有效的。事实并非如此。如果 ANTHROPIC_API_KEY 存在，文档说明配置文件将被跳过。当命令指向错误的 workspace 时，这是我首先会检查的地方。

第三个错误假设是 --format raw 和 --raw-output 是一样的。 --raw-output 与 jq -r 在字符串方面进行了比较。 --format raw 会打印原始响应字节，并且在列表端点上的行为有所不同。

调试与 Shell 自动补全

若要进行调试，请添加 --debug。文档说明它会将确切的 HTTP 请求和响应打印到 stderr，并会对 API 密钥进行脱敏处理。若要检查错误，请使用 --format-error 和 --transform-error 来过滤错误响应。

ant --debug beta:agents list

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

文档还提到，补全脚本适用于 bash、zsh、fish 和 PowerShell。这一点很重要，因为命令树非常庞大。自动补全可以减少在输入测试版资源名称、嵌套资源以及特定于端点的标志时出错的概率。

结论

如果你需要类型化的应用程序集成、长生命周期的 SDK 抽象，或嵌入在服务内部的运行时行为，则无需使用它。CLI 的优势在于开发者、终端、平台资源以及能够读取结构化命令输出的 Agent 之间的交互边界。

FAQ

术语表

ant

Anthropic 用于 Claude Platform API 资源的命令行工具。

Messages API

用于发送模型消息并接收助手响应的 Claude API 端点。

托管 Agent

一种配置了模型、系统提示词、工具和运行时行为的 Claude Platform Agent 资源。

工作区 (Workspace)

一种 Claude Console 作用域，用于控制凭据可以访问哪些 API 资源。

配置文件 (Profile)

一种命名的 CLI 配置，用于切换凭据、工作区及相关设置。

GJSON

一种路径语法，用于 --transform 提取或重塑 JSON 响应。

JSONL

换行符分隔的 JSON，适用于每个列表项需要以单行流式传输的场景。

工作负载身份联合 (Workload Identity Federation)

文档推荐用于 CI、服务器和容器的非交互式身份验证路径。

所有官方来源与链接

根据本文的发布限制，未使用任何社区网站、Reddit 帖子、Hacker News 评论、非官方博客文章或第三方教程。