CLI

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.

Installation

Check the installation:

ant --version

Authentication

Interactive login

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/<profile>.json. The first login for a profile also creates configs/<profile>.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.

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:

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

Manage profiles

The ant profile subcommands inspect and edit profile state directly:

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

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

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.

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:

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.