Repository Public
1---2title: Using the CLI3url: https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using4description: Command structure, output formats, GJSON transforms, request bodies, and debugging for the ant CLI.5---67This page covers the `ant` CLI's input and output mechanics that apply across every endpoint. To install and authenticate, see the [Quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart). To chain commands and version-control resources, see [CLI scripting and automation](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting).89## Command structure1011Commands follow a `resource action` pattern. Nested resources use colons:1213```text wrap14ant <resource>[:<subresource>] <action> [flags]15```1617Run `ant --help` for the full resource list, or append `--help` to any subcommand for its flags.1819Resources in beta (including agents, sessions, deployments, and environments) 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).2021```bash22ant models list23ant messages create --model claude-opus-5 --max-tokens 1024 ...24ant beta:agents retrieve --agent-id agent_01...25ant beta:sessions:events list --session-id session_01...26```2728### Global flags2930| Flag | Description |31| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |32| `--profile` | Named profile to use for this invocation (equivalent to setting `ANTHROPIC_PROFILE`). See [Switch between workspaces](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication#switch-between-workspaces). |33| `--format` | Output format: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` |34| `--transform` | Filter or reshape the response with a [GJSON path](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#transform-output-with-gjson) |35| `-r`, `--raw-output` | Print string results without surrounding quotes, like `jq -r` |36| `--base-url` | Override the API base URL |37| `--workspace-id` | Optional. Workspace ID (`wrkspc_...`) to send as the `anthropic-workspace-id` header, for API keys with access to multiple workspaces (equivalent to setting `ANTHROPIC_WORKSPACE_ID`). See [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) commands take their own `--workspace-id`, which names the workspace they manage instead. |38| `--debug` | Print full HTTP request and response to stderr |39| `--format-error`, `--transform-error` | Same as `--format` and `--transform` but applied to [error responses](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting#inspect-errors) |4041## Output formats4243`auto` pretty-prints JSON and is the default for commands that create or modify resources. List and retrieve commands default to the [interactive explorer](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#interactive-explorer) when writing to a terminal, and to pretty-printed JSON when piped. Override either default with `--format`:4445```bash46ant models retrieve --model-id claude-opus-5 --format yaml47```4849```yaml Output50type: model51id: claude-opus-552display_name: Claude Opus 553created_at: "2026-07-24T00:00:00Z"54...55```5657List 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.5859### Interactive explorer6061The 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:6263```bash64ant models list --format explore65```6667## Transform output with GJSON6869Use `--transform` to reshape responses before printing. The expression is a [GJSON path](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). For list endpoints the transform runs against each item individually, not the envelope:7071```bash72ant beta:agents list \73 --transform "{id,name,model}" \74 --format jsonl75```7677```jsonl Output78{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5"}79{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}80{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5"}81```8283### Extract a scalar8485To 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:8687```bash88AGENT_ID=$(ant beta:agents create \89 --name "My Agent" \90 --model '{id: claude-opus-5}' \91 --transform id --raw-output)9293printf '%s\n' "$AGENT_ID"94```9596```text Output wrap97agent_011CYm1BLqPXpQRk5khsSXrs98```99100<Note>101 `--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.102</Note>103104## Passing request bodies105106The 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 multiline bodies, and use **`@file` references** to pull file contents into any string or binary field.107108### Flags109110Scalar fields map directly to flags. Structured fields accept a relaxed YAML-like syntax (unquoted keys, optional quotes around strings) or strict JSON:111112```bash113ant beta:sessions create \114 --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \115 --environment-id env_01595EKxaaTTGwwY3kyXdtbs \116 --title "CLI docs test session"117```118119Repeatable flags build arrays. Each `--tool` or `--event` appends one element:120121```bash122ant beta:agents create \123 --name "Research Agent" \124 --model '{id: claude-opus-5}' \125 --tool '{type: agent_toolset_20260401}' \126 --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'127```128129### Stdin130131Pipe 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](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using#extract-a-scalar):132133```bash134echo '{"description": "Updated test agent.", "version": 1}' | \135 ant beta:agents update --agent-id "$AGENT_ID"136```137138Heredocs work the same way and are convenient for multiline YAML. Quote the delimiter (as in `<<'YAML'`) to disable variable expansion inside the body.139140```bash141ant beta:agents create <<'YAML'142name: Research Agent143model: claude-opus-5144system: |145 You are a research assistant. Cite sources for every claim.146tools:147 - type: agent_toolset_20260401148YAML149```150151### File references152153Flags that take a file path, such as `--file` on the upload command, accept a bare path:154155```bash156ant files upload --file ./report.pdf157```158159To inline a file's contents into a string-valued field, prefix the path with `@`:160161```bash162ant beta:agents create \163 --name "Researcher" --model '{id: claude-opus-5}' \164 --system @./prompts/researcher.txt165```166167Inside structured flag values, wrap the path in quotes. To send a PDF to the Messages API:168169```bash170ant messages create \171 --model claude-opus-5 \172 --max-tokens 1024 \173 --message '{role: user, content: [174 {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},175 {type: text, text: "Extract the text from this scanned document."}176 ]}' \177 --transform 'content.#(type=="text").text' --raw-output178```179180The 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`).181182## Debugging183184Add `--debug` to any command to print the exact HTTP request and response (headers and body) to stderr. API keys are redacted.185186```bash187ant --debug beta:agents list188```189190```text Output wrap191GET /v1/agents?beta=true HTTP/1.1192Host: api.anthropic.com193Anthropic-Beta: managed-agents-2026-04-01194Anthropic-Version: 2023-06-01195X-Api-Key: <REDACTED>196...197```198199## Available resources200201Every API resource the CLI exposes is documented in the [API reference](https://platform.claude.com/docs/en/api/cli/messages/create). For a local listing, run `ant --help`, and append `--help` to any subcommand for its flags and parameters.202203## Next steps204205<CardGroup cols={3}>206 <Card title="CLI scripting and automation" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting">207 Version-control API resources, scripting patterns, and use from Claude Code208 </Card>209210 <Card title="API reference" icon="book" href="https://platform.claude.com/docs/en/api/cli/messages/create">211 Endpoint-specific parameters, request fields, and response schemas212 </Card>213214 <Card title="CLI authentication options" icon="lock" href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication">215 API keys, headless hosts, multiple workspaces, and named profiles216 </Card>217</CardGroup>218