CLI

Interact with the Claude API directly from your terminal with the ant command-line tool

The ant CLI provides access to the Claude API from your terminal. Every API resource is exposed as a subcommand, with output formatting, response filtering, and support for YAML or JSON file input that make it practical for both interactive exploration and automation.

Compared to calling the API with curl, ant lets you build request bodies from typed flags or piped YAML rather than hand-written JSON, inline file contents into string fields with an @path reference, and extract fields from the response with a built-in --transform query (no separate JSON tooling required). List endpoints paginate automatically. Claude Code understands how to use ant natively.

Info

For endpoint-specific parameters and response schemas, see the API reference. This page covers CLI-specific features and workflows that apply across all endpoints.

Installation

brew install anthropics/tap/ant

For Linux environments, download the release binary directly.

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

You can find all releases on the GitHub releases page.

You may also install the CLI from source using go install. Requires Go 1.22 or later.

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

The binary is placed in $(go env GOPATH)/bin. Add it to your PATH if it isn't already:

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

Check the installation:

ant --version

Authentication

ant auth login lets you call the API without creating or managing an API key. It opens a browser-based OAuth flow against the Claude Console and stores the resulting credentials under $ANTHROPIC_CONFIG_DIR (see Configuration directory for the OS-specific default). On a remote host or in any environment without a local browser, pass --no-browser to print the authorize URL and paste the returned code back into the terminal.

ant auth login

# On a remote host without a browser:
ant auth login --no-browser

# Bind to a specific workspace and skip the browser picker:
ant auth login --workspace-id wrkspc_01...

# If the named profile you pass with --profile doesn't exist,
# a new named profile will be created with that name.
ant auth login --profile <profile-name>

During the browser flow, you select an organization and then a workspace. The issued token is scoped to that workspace, so the CLI can only see resources that belong to it. Pass --workspace-id to bind directly and skip the picker. To work in more than one workspace, see Switch between workspaces.

Interactive login is intended for local development and scripting on your own machine. For non-interactive workloads such as CI, servers, and containers, use Workload Identity Federation instead.

Login writes credentials to credentials/.json. The first login for a profile also creates configs/.json and sets it as the active profile. To remove stored credentials, run ant auth logout, or ant auth logout --all to clear every profile.

API key

The CLI also reads your API key from the ANTHROPIC_API_KEY environment variable. Get a key from the Claude Console.

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

Open a new terminal for the change to take effect.

To override the key for a single invocation, pass --api-key. To point at a different API host, set ANTHROPIC_BASE_URL or pass --base-url.

Check authentication status

ant auth status prints the credential source the CLI selected (API key environment variable, OAuth login, federation, or profile), the active profile, the workspace the active token is bound to, and the configuration directory paths. Use it to diagnose why a workload picked the wrong credential or workspace.

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)

Read the (active) rows to see which credential source and workspace won. The command reports status rather than performing a health check, so don't script against the exit status. For the full ordering of credential sources, see Credential precedence.

Switch between workspaces

An interactive-login token is bound to a single workspace. To use the CLI against more than one workspace, log in to each under its own named profile, then switch between them:

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. Create the profile (interactive; pick the other workspace in the
#    browser, or pass --workspace-id to skip the picker):
# ant auth login --profile other-ws

# 2. Make it the default for subsequent commands:
ant profile activate other-ws

# 3. Or select it for a single command without changing the default:
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

Run ant auth status to confirm which profile and workspace are active.

Note

Profiles are only consulted when no API key is set. If ANTHROPIC_API_KEY is present in your environment, it overrides every profile and these commands all use whatever workspace that key is scoped to. Unset it before switching profiles.

Manage profiles

The ant profile subcommands inspect and edit profile state directly:

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

The writable keys for ant profile set are workspace_id, base_url, organization_id, scope, client_id, and console_url. Setting workspace_id records the target workspace in the profile config but does not rebind credentials that were already issued; run ant auth login again under that profile to mint a token for the new workspace.

For the profile file schema and the federation block, see Profile configuration file. For Workload Identity Federation, see the Authentication overview and the WIF reference.

Send your first request

With the binary installed and authenticated, call the 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 /*, ... */ }
}

The response is the full API object, pretty-printed because stdout is a terminal. The rest of this page covers how to reshape that output, pass complex request bodies, and chain commands together.

Command structure

Commands follow a resource action pattern. Nested resources use colons:

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

Run ant --help for the full resource list, or append --help to any subcommand for its flags.

Resources in beta (including agents, sessions, deployments, environments, and skills) live under the beta: prefix. Commands in this namespace automatically send the appropriate anthropic-beta header for that resource, so you don't need to pass it yourself. Use --beta <header> only to override the default (for example, to opt into a different schema version).

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

Global flags

Flag	Description
`--profile`	Named profile to use for this invocation (equivalent to setting `ANTHROPIC_PROFILE`). See Switch between workspaces.
`--format`	Output format: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore`
`--transform`	Filter or reshape the response with a GJSON path
`-r`, `--raw-output`	Print string results without surrounding quotes, like `jq -r`
`--base-url`	Override the API base URL
`--debug`	Print full HTTP request and response to stderr
`--format-error`, `--transform-error`	Same as `--format` and `--transform` but applied to error responses

Output formats

auto pretty-prints JSON and is the default for commands that create or modify resources. List and retrieve commands default to the interactive explorer when writing to a terminal, and to pretty-printed JSON when piped. Override either default with --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"
...

List endpoints auto-paginate. In the default formats each item is written separately (one compact JSON object per line in jsonl mode, a stream of YAML documents in yaml mode), which streams cleanly into head, grep, and --transform filters.

Interactive explorer

The explorer is a fold-and-search TUI for browsing large responses. Arrow keys expand and collapse nodes, / searches, q exits. List and retrieve commands open it by default when connected to a terminal. Pass --format explore to open it explicitly:

ant models list --format explore

Transform output with GJSON

Use --transform to reshape responses before printing. The expression is a GJSON path. For list endpoints the transform runs against each item individually, not the envelope:

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

Extract a scalar

To capture a single field as an unquoted string (for example, the ID of a newly created resource), pair --transform with --raw-output. The result prints without JSON quotes and is ready to assign to a shell variable:

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

Note

--raw-output is distinct from --format raw. --raw-output strips JSON quotes from string results, like jq -r. --format raw prints the response body's raw JSON bytes without auto-paginating; on list endpoints it applies --transform to the pagination envelope rather than to each item.

Passing request bodies

The right input mechanism depends on the shape of the data: use flags for scalar fields and short structured values, pipe a stdin document for nested or multi-line bodies, and use @file references to pull file contents into any string or binary field.

Flags

Scalar fields map directly to flags. Structured fields accept a relaxed YAML-like syntax (unquoted keys, optional quotes around strings) or strict JSON:

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

Repeatable flags build arrays. Each --tool or --event appends one element:

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}}}}'

Stdin

Pipe a JSON or YAML document to stdin to supply the full request body. Fields from stdin are merged with flags, with flags taking precedence. Here version is the optimistic-locking token returned by an earlier retrieve, and $AGENT_ID was captured as in Extract a scalar:

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

Heredocs work the same way and are convenient for multi-line YAML. Quote the delimiter (as in <<'YAML') to disable variable expansion inside the body.

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 references

Flags that take a file path, such as --file on the upload command, accept a bare path:

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

To inline a file's contents into a string-valued field, prefix the path with @:

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

Inside structured flag values, wrap the path in quotes. To send a PDF to the Messages API:

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

The CLI detects the file type and encodes binary files as base64 automatically. To force a specific encoding use @file:// for plain text or @data:// for base64. Escape a literal leading @ with a backslash (\@username).

Version-controlling API resources

You can use the CLI to version control API resources such as skills, agents, environments, or deployments as YAML files in your repository and keep them in sync with the Claude API.

Note

For more information on these resources, see Managed Agents.

Define your agent

Write the agent definition to 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 the agent
```
ant beta:agents create < summarizer.agent.yaml
```
```
{
  "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
  "version": 1,
  "name": "Summarizer",
  "model": "claude-sonnet-4-6"
  /* ... */
}
```
Note the id from the response. You'll pass it to the session create command in a later step.
💡
Tip
Check summarizer.agent.yaml into your repository and keep it in sync with the API in your CI pipeline. The update command needs the agent ID and current version as flags:
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
Define the environment
A session runs in an environment, which defines the container it executes in. Write the environment definition to summarizer.environment.yaml:
```
name: summarizer-env
config:
  type: cloud
  networking:
    type: unrestricted
```
Create the environment
```
ant beta:environments create < summarizer.environment.yaml
```
```
{
  "id": "env_01595EKxaaTTGwwY3kyXdtbs",
  "name": "summarizer-env"
  /* ... */
}
```
Note the id from the response. You'll pass it to the session create command in a later step.
💡
Tip
Check summarizer.environment.yaml into your repository and keep it in sync with the API in your CI pipeline. The update command needs the environment ID as a flag:
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

Start a session

Paste the agent id and environment id from the previous outputs into the session create command:

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

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

Send a user message

Copy the session id from the previous output into --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."}]}'

Read the conversation

--transform runs against each listed event, so this prints the text of every message in order. --format auto overrides the interactive explorer that list commands open by default in a terminal:

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

To watch a session as it runs, use ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K. Events are written to stdout as they arrive.

Scripting patterns

The CLI is designed to compose with standard shell tooling.

Chain list output into a second command

--transform id --raw-output on a list endpoint emits one bare ID per line, so standard tools such as head and xargs apply directly. Capture the first result, then pass it to a follow-up command:

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

Inspect errors

The --transform-error and --format-error flags apply the same filtering to error responses. --raw-output does not apply to errors, so use --format-error yaml for an unquoted scalar. Extract only the error message:

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.

Use the CLI from Claude Code

Claude Code knows out of the box how to use the ant CLI. With the CLI installed and authenticated, you can ask Claude Code to operate on your API resources directly. For example:

"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 shells out to ant, parses the structured output, and reasons over the results (no custom integration code required).

Debugging

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

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 completion

The CLI ships completion scripts for bash, zsh, fish, and PowerShell. Generate and install one for your shell:

ant @completion zsh > "${fpath[1]}/_ant"
# Restart your shell or run: 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
# To persist across sessions:
# ant @completion powershell >> $PROFILE

Available resources

Every API resource the CLI exposes is documented in the API reference. For a local listing, run ant --help, and append --help to any subcommand for its flags and parameters.

CLI

Installation

Authentication

Interactive login

API key

Check authentication status

Switch between workspaces

Manage profiles

Send your first request

Command structure

Global flags

Output formats

Interactive explorer

Transform output with GJSON

Extract a scalar

Passing request bodies

Flags

Stdin

File references

Version-controlling API resources

Define your agent

Create the agent

Define the environment

Create the environment

Start a session

Send a user message

Read the conversation

Scripting patterns

Chain list output into a second command

Inspect errors

Use the CLI from Claude Code

Debugging

Shell completion

Available resources