Repository Public
1---2title: CLI scripting and automation3url: https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting4description: Version-control API resources as files with ant apply, chain ant CLI commands in scripts, operate on resources from Claude Code, and authenticate curl calls with CLI credentials.5---67This page covers task-oriented workflows built on the `ant` CLI. For the underlying flags and output options, see [Using the CLI](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/using).89## Version-controlling API resources1011To keep agents, environments, and other Claude Managed Agents resources as files in your repository, see [Manage resources as code with ant apply](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply).1213### Run the applied agent from the shell1415Once an agent and environment exist, you can drive a session from the shell:1617<Steps>18 <Step title="Start a session">19 Pass the agent and environment IDs to the session create command. After `ant apply`, read them from `claude-lock.json`: each entry under `resources` has an `id`, and for the project in [Manage resources as code with ant apply](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply) the entries are `./agents/summarizer.md` and `./environments/cloud.yaml`.2021 ```bash22 ant beta:sessions create \23 --agent agent_011CYm1BLqPXpQRk5khsSXrs \24 --environment-id env_01595EKxaaTTGwwY3kyXdtbs \25 --title "Summarization task"26 ```2728 ```json Output29 {30 "id": "session_01JZCh78XvmxJjiXVy3oSi7K",31 "status": "running"32 /* ... */33 }34 ```35 </Step>3637 <Step title="Send a user message">38 Copy the session `id` from the previous output into `--session-id`:3940 ```bash41 ant beta:sessions:events send \42 --session-id session_01JZCh78XvmxJjiXVy3oSi7K \43 --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'44 ```45 </Step>4647 <Step title="Read the conversation">48 Once the agent has replied, list the events. `--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:4950 ```bash51 ant beta:sessions:events list \52 --session-id session_01JZCh78XvmxJjiXVy3oSi7K \53 --transform 'content.0.text' \54 --raw-output \55 --format auto56 ```5758 ```text Output wrap59 Summarize the benefits of type safety in one sentence.60 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.61 ```6263 <Tip>64 To watch a session as it runs, use `ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K --format jsonl`, which writes each event to stdout as it arrives. Without `--format`, a terminal opens the interactive explorer instead.65 </Tip>66 </Step>67</Steps>6869## Scripting patterns7071The CLI is designed to compose with standard shell tooling.7273### Chain list output into a second command7475`--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:7677```bash78FIRST_AGENT=$(ant beta:agents list --transform id --raw-output | head -1)7980ant beta:agents:versions list \81 --agent-id "$FIRST_AGENT" \82 --transform "{version,created_at}" --format jsonl83```8485### Inspect errors8687The `--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:8889```bash90ant beta:agents retrieve --agent-id bogus \91 --transform-error error.message --format-error yaml 2>&192```9394```text Output wrap95GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found96Agent not found.97```9899## Use the CLI from Claude Code100101[Claude Code](https://code.claude.com/docs/en/overview) can use the `ant` CLI out of the box. With the CLI installed and authenticated, you can ask Claude Code to operate on your API resources directly. For example:102103* "List my recent agent sessions and summarize which ones errored."104* "Upload every PDF in `./reports` to the Files API and print the resulting IDs."105* "Pull the events for session `session_01...` and tell me where the agent got stuck."106107Claude Code shells out to `ant`, parses the structured output, and reasons over the results (no custom integration code required).108109## Authenticate curl requests with CLI credentials110111Scripts that call the API with `curl` or another HTTP client can use the credentials stored by [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart#authentication) instead of a static API key. The OAuth access token goes in the `Authorization` header as a bearer token; the `x-api-key` header is only for static API keys.112113`ant auth print-credentials --access-token` prints the active profile's access token, refreshing it first if it is expired or near expiry:114115```bash cURL116curl https://api.anthropic.com/v1/messages \117 -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \118 -H "anthropic-version: 2023-06-01" \119 -H "content-type: application/json" \120 -d '{121 "model": "claude-opus-5",122 "max_tokens": 256,123 "messages": [{"role": "user", "content": "hi"}]124 }'125```126127<Note>128 Keep `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` unset when working from a CLI login. Either variable takes precedence over the login for `ant` commands (see [Credential precedence](https://platform.claude.com/docs/en/manage-claude/wif-reference#credential-precedence)) and can silently route them to a different organization or workspace.129</Note>130131Run [`ant auth status`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication#check-authentication-status) to confirm which organization and workspace you are logged in to; it warns when an environment variable is overriding your login.132