The ant CLI: interact with the Claude API from your terminal

The ant CLI is a command-line client for the Claude API. It gives you access to every API endpoint — messages, models, batch jobs, files, agents, sessions — directly from your terminal without writing any code.

Released April 8, 2026.

How it differs from Claude Code

Claude Code is an AI coding assistant that runs in your terminal and helps you write, debug, and navigate code. The ant CLI is different: it is a low-level API client, like curl, but with typed flags, YAML input support, and automatic pagination. You use it to call API endpoints directly — inspect models, send messages, manage agents, check batch results.

The two tools are complementary. Claude Code knows how to use ant natively, so you can ask Claude Code to run API operations by describing them in natural language.

Installation

macOS (Homebrew):

brew install anthropics/tap/ant

# Unquarantine the binary on macOS
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"

Linux / WSL:

VERSION=1.0.0
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 (from source, requires Go 1.22+):

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

Check the installation: ant --version

Authentication

Set your API key as an environment variable. Get a key from platform.claude.com/settings/keys.

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

Send your first message

ant messages create \
  --model claude-sonnet-4-6 \
  --max-tokens 1024 \
  --message '{role: user, content: "What is the capital of France?"}'

The response is the full API JSON object, pretty-printed in the terminal. When piped or redirected, it emits compact JSON automatically.

{
  "model": "claude-sonnet-4-6",
  "id": "msg_01YMmR5XodC5nTqMxLZMKaq6",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 18, "output_tokens": 9 }
}

Command structure

Commands follow a resource action pattern:

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

ant models list                                    # list available models
ant messages create --model ...                    # send a message
ant beta:agents list                               # list agents (managed agents beta)
ant beta:sessions:events list --session-id ...     # list events in a session

Resources in beta — agents, sessions, deployments, environments, skills — use the beta: prefix. The CLI sends the required beta header automatically; you do not need to pass it yourself.

Run ant --help for the full resource list. Append --help to any subcommand for its flags.

Transform and filter output

The --transform flag takes a GJSON path and reshapes the response before printing. For list endpoints, the transform runs against each item individually:

# Print only the ID and model for each agent
ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

{"id": "agent_011CYm1BLqPX...", "name": "Research Agent", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYkVwfaEt...", "name": "Support Agent", "model": "claude-haiku-4-5"}

To capture a scalar into a shell variable, pair --transform with --format yaml — YAML emits scalars without quotes:

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

printf '%s\n' "$AGENT_ID"
# agent_011CYm1BLqPXpQRk5khsSXrs

Passing request bodies

Three mechanisms, depending on the shape of your data:

Flags for scalar fields and short structured values (unquoted YAML keys work):

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Research session"

Stdin for full request bodies as JSON or YAML. Heredocs work cleanly for multi-line YAML; quote the delimiter to disable variable expansion:

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-4-6
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

@file references to inline a file's contents into a string field — useful for system prompts:

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

For binary files (PDFs, images), the CLI base64-encodes them automatically when you use @file inside a structured field.

Version-controlling API resources

YAML input makes ant useful for keeping API resources in version control. Define an agent, environment, or skill as a YAML file, check it in, and sync it from CI:

# 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

Create it:

ant beta:agents create < summarizer.agent.yaml

Update from CI (pass agent ID and current version as flags):

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

This is infrastructure-as-code for prompts and agent configurations.

Claude Code integration

With ant on your PATH and ANTHROPIC_API_KEY set, Claude Code can operate on your API resources directly. Examples of what you can ask Claude Code:

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

Claude Code shells out to ant, parses the structured output, and reasons over the results without any custom integration code from you.

Debugging

Add --debug to any command to print the full HTTP request and response (including headers) to stderr. API keys are redacted.

ant --debug beta:agents list

When ant makes sense vs. the SDK

The Python or TypeScript SDK is the right choice when you're writing production application code — it handles types, async, and integrates into your codebase.

ant is better for:

• Exploring the API interactively before writing code
• Shell scripts and CI pipelines that call API endpoints
• Syncing agent/environment/skill definitions from YAML in version control
• Debugging a specific request — --debug shows you exactly what was sent and received

Official docs

Full reference: platform.claude.com/docs/en/api/sdks/cli

GitHub releases: github.com/anthropics/anthropic-cli/releases