Jonathon's AI Wiki

ant — the Claude Platform CLI

5 min read

Source: ai-research/ant-cli-claude-platform-docs-2026-06-03.md (official Claude Platform docs, platform.claude.com/docs/en/api/sdks/cli), raw/x-account-claudedevs-2061877343078244459.md (@ClaudeDevs launch announcement, 2026-06-02), raw/x-bookmarks-recent-digest-2026-06-04.md (launch-thread follow-up: built-in /claude-api skill + brew/curl/go install)

ant is Anthropic’s first-party command-line client for the Claude Platform API. Every API resource — Messages, models, files, and the beta agents / sessions / environments / skills surface — is exposed as a terminal subcommand, with OAuth login, output formatting, response filtering, and YAML/JSON/stdin request bodies. It is built to be driven both interactively and from scripts/CI, and Claude Code knows how to call it natively (it shells out to ant and reasons over the structured output, no integration code required).

Key Takeaways

  • resource action command grammar, colons for nesting. ant models list, ant messages create, ant beta:agents retrieve, ant beta:sessions:events list. ant --help lists resources; append --help to any subcommand for its flags.
  • Beta resources auto-send the beta header. Agents, sessions, deployments, environments, and skills live under the beta: prefix; commands there automatically attach the right anthropic-beta header (e.g. managed-agents-2026-04-01) — no manual header needed. Use --beta only to override.
  • OAuth login, no API key required. ant auth login runs a browser OAuth flow against the Claude Console and scopes the token to a selected workspace; --no-browser covers headless/remote hosts. It still reads ANTHROPIC_API_KEY if set (key overrides profiles). ant auth status reports which credential source + workspace won.
  • Named profiles map to workspaces. A login token binds to one workspace; create a profile per workspace (ant auth login --profile other-ws), then ant profile activate / ant --profile / ANTHROPIC_PROFILE= to switch. For non-interactive CI use Workload Identity Federation, not interactive login.
  • Output is scriptable by design. --format auto|json|jsonl|yaml|pretty|raw|explore; list endpoints auto-paginate and stream one item per line in jsonl/yaml. --transform reshapes the response with a GJSON path (runs per-item on lists); --raw-output strips quotes like jq -r so you can capture an ID straight into a shell variable. An interactive fold/search explorer TUI opens by default for list/retrieve in a terminal.
  • Three ways to pass a request body. Typed flags for scalars and short structured values (relaxed YAML or strict JSON; repeatable flags build arrays); piped stdin YAML/JSON for full/nested bodies (merged with flags, flags win; heredocs for multi-line); @file references to inline file contents into a string field (auto base64 for binaries; @file:// / @data:// to force encoding).
  • Version-control your API resources as YAML. Define a skill/agent/environment/deployment as a .yaml file, ant beta:agents create < agent.yaml, commit it, and keep it in sync in CI with ant beta:agents update --agent-id ... --version N < agent.yaml (optimistic-locking via version). This is the GitOps story for Managed Agents.
  • End-to-end agent loop from the shell. ant beta:agents create → ant beta:environments create → ant beta:sessions create --agent ... --environment-id ... → ant beta:sessions:events send → ant beta:sessions:events list --transform 'content.0.text' (or ... stream to watch live).
  • --debug prints the exact HTTP request/response (headers + body, API keys redacted) — the fastest way to see which beta header or workspace a call used. Ships shell completion for bash/zsh/fish/PowerShell.

Why It Matters

  • Closes the “curl is painful, SDK is heavy” gap. For ops, one-off API calls, and CI sync of Managed Agents, ant is lower-friction than hand-written JSON + jq and lighter than wiring the Agent SDK — typed flags, GJSON transforms, and YAML stdin replace the JSON-tooling glue.
  • Makes Managed Agents a Git-native artifact. Treating agents/environments/skills as version-controlled YAML synced via CI is the operational complement to the production primitives and self-hosted sandboxes — config review, rollback, and reproducibility for agent definitions.
  • It’s the substrate Claude Code reaches for. Because Claude Code knows ant out of the box, “list my agent sessions and summarize which errored” becomes a shell-out, not a custom tool — the same agent-shells-out-to-CLI pattern behind dynamic workflows.

Implementation

Tool/Service: ant — Claude Platform CLI (first-party, Anthropic). Docs: platform.claude.com/docs/en/api/sdks/cli.

Setup:

  1. Install the binary; confirm with ant --version.
  2. ant auth login (or --no-browser on a remote host); pick org + workspace. Or set ANTHROPIC_API_KEY.
  3. ant auth status to confirm the active credential source + workspace.
  4. First call: ant messages create --model claude-opus-4-8 --max-tokens 1024 --message '{role: user, content: "Hello, Claude"}'.

Cost: The CLI is free tooling; calls bill against your Claude Platform workspace at standard API rates. ^[inferred — pricing not stated on the CLI docs page]

Integration notes:

  • For CI / servers / containers use Workload Identity Federation, not interactive login.
  • --transform id --raw-output | head -1 | xargs ... chains list output into a follow-up command.
  • --transform-error error.message --format-error yaml extracts just the message from a failed call (--raw-output doesn’t apply to errors).

Try It

  1. Install via brew, curl, or go, then ant auth login and ant models list --format explore to browse models in the TUI.
  2. Define a tiny agent in summarizer.agent.yaml (name/model/system/tools), ant beta:agents create < summarizer.agent.yaml, capture the ID with --transform id --raw-output, then run a session end-to-end and read it back with --transform 'content.0.text'.
  3. From Claude Code (CLI installed + authed), ask: “List my recent agent sessions and summarize which ones errored” — watch it shell out to ant.

Open Questions

  • Distribution/install Resolved (2026-06-03): install via brew, curl, or go (@ClaudeDevs follow-up post in the launch thread).
  • Relationship to the claude-api skill Resolved (2026-06-03): it is a built-in Claude Code skill named /claude-api — Claude Code shells out to ant (list sessions, upload a folder of PDFs, debug a run) and reads the results back with no glue code (@ClaudeDevs).
  • Pricing / rate-limit specifics for CLI-issued calls beyond standard workspace API billing.

Graph View

Backlinks