Repository Public
1---2title: Manage resources as code with ant apply3url: https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply4description: Declare agents, environments, skills, memory stores, and deployments as files in your repository and keep the API's resources in sync with them using ant apply.5---67`ant apply` creates and updates Claude API resources from files: agents, environments, skills, memory stores, and deployments. They live in your repository and change through the same review as your code. You describe each resource in a file, run `ant apply`, and approve the plan it shows. Then you commit the `claude-lock.json` it writes, so the next run updates the same resources instead of creating new ones.89To install and authenticate the CLI, see the [CLI quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart). `ant apply` requires CLI version 1.30.0 or later.1011## Apply your first agent1213Write the agent as a Markdown file under `agents/` and apply it:1415<MultiFileExample language="cli" label="CLI">16 ```bash CLI17 ant apply agents/summarizer.md18 ```1920 <File filename="agents/summarizer.md">21 ```markdown22 ---23 name: Summarizer24 model: claude-opus-525 tools:26 - type: agent_toolset_2026040127 ---2829 You are a helpful assistant that writes concise summaries.30 ```31 </File>32</MultiFileExample>3334The frontmatter holds the agent's configuration (the fields from [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup)) and the body is its system prompt. `ant apply` [infers](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply#kind-inference) that the file is an agent from its path, here the `agents/` directory.3536In an interactive terminal, `ant apply` prints the plan and waits for your approval:3738```text Output wrap39First apply ./claude-lock.json does not exist yet and will be created4041Resources will be created with42 credentials API key (--api-key / ANTHROPIC_API_KEY)43 host api.anthropic.com44 organization 1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f45 workspace wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ4647Preview ./claude-lock.json (new)4849± Name Plan50+ ./agents/summarizer.md create5152Resources + 1 to create5354Apply these changes? (y)es / (n)o / (d)etails y5556Apply ./claude-lock.json5758± Name Status59+ ./agents/summarizer.md created agent_011CYm1BLqPXpQRk5khsSXrs6061Resources + 1 created6263State written to ./claude-lock.json64```6566Answer `d` to see details first: the fields of each new resource, or a field-by-field diff of each update. `--dry-run` prints that detailed plan and exits without changing anything.6768To change the agent, edit the file and run `ant apply` again. The plan then shows an update instead of a create.6970## Commit claude-lock.json7172The first `ant apply` writes `claude-lock.json`, the lockfile, in the directory you run it from, so run it from the repository root. It records the ID of the resource each file created and the organization and workspace the resources live in:7374```json claude-lock.json75{76 "version": 1,77 "origin": {78 "base_url": "https://api.anthropic.com",79 "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f",80 "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"81 },82 "resources": {83 "./agents/summarizer.md": {84 "kind": "agent",85 "id": "agent_011CYm1BLqPXpQRk5khsSXrs",86 "version": "1",87 "hash": "d23251c8d99b3613a64f3f8d87f5fad4",88 "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94"89 }90 }91}92```9394Commit it with your files. It's how the next run, on your machine or in CI, finds these resources instead of creating them again, and it's where you read an agent's ID to [start a session](https://platform.claude.com/docs/en/managed-agents/sessions). The two hashes fingerprint what was last sent and what the API returned. That's how a later run notices an edited file, or a resource changed outside these files.9596## Grow it into a project9798You can declaratively define the other resources as files as well. A file holds the request body you would send to that kind's create endpoint:99100* An [environment](https://platform.claude.com/docs/en/managed-agents/environments) is a YAML file in `environments/`.101* A [memory store](https://platform.claude.com/docs/en/managed-agents/memory) is a YAML file in `memory_stores/`.102* A [deployment](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments) is a Markdown file in `deployments/`: the frontmatter is the request body and the prose becomes the message that starts each session.103* A [skill](https://platform.claude.com/docs/en/managed-agents/skills) is a directory with a `SKILL.md` at its root, conventionally under `skills/`, uploaded as one bundle.104105Any resource except a skill can be written as YAML, JSON, or Markdown. In Markdown, the frontmatter is the body and the prose fills the kind's text field: an agent's `system`, an environment's or memory store's `description`, a deployment's first message.106107Resources refer to each other by path. Wherever the API expects another resource's ID, write the relative path to that resource's file instead. In this project, the reviewer agent lists `../skills/pr-summary` under `skills`, the lead agent lists `./reviewer.md` in its roster, and the deployment names its agent, environment, and memory store by path. `ant apply` creates them in dependency order and fills in the real IDs. The project has six files:108109<MultiFileExample variant="explorer">110 <File filename="agents/reviewer.md">111 ```markdown112 ---113 name: Code reviewer114 model: claude-opus-5115 tools:116 - type: agent_toolset_20260401117 skills:118 - ../skills/pr-summary119 ---120121 You review pull requests for correctness, security, and readability.122 ```123 </File>124125 <File filename="agents/lead.md">126 ```markdown127 ---128 name: Engineering lead129 model: claude-opus-5130 multiagent:131 type: coordinator132 agents:133 - ./reviewer.md134 ---135136 You coordinate engineering work. Delegate code review to the reviewer.137 ```138 </File>139140 <File filename="skills/pr-summary/SKILL.md">141 ```markdown142 ---143 name: pr-summary144 description: Summarize a pull request's changes and risks in the team's review format.145 ---146147 # PR summary148149 List what changed, why, and anything a reviewer should look at closely, in three short sections.150 ```151 </File>152153 <File filename="environments/cloud.yaml">154 ```yaml155 name: review-env156 description: Cloud container with unrestricted networking for review sessions.157 config:158 type: cloud159 networking:160 type: unrestricted161 ```162 </File>163164 <File filename="memory_stores/review-notes.yaml">165 ```yaml166 name: Review notes167 description: Recurring issues and house-style decisions the reviewer has recorded between runs.168 ```169 </File>170171 <File filename="deployments/nightly.md">172 ```markdown173 ---174 name: Nightly review175 agent: ../agents/reviewer.md # the API's agent field: sent as {type: agent, id, version}176 environment_id: ../environments/cloud.yaml # sent as the environment's ID177 resources:178 - path: ../memory_stores/review-notes.yaml179 access: read_write180 schedule:181 type: cron182 expression: "0 3 * * *"183 timezone: America/Los_Angeles184 ---185186 Review any open pull requests. Start with the oldest.187 ```188 </File>189</MultiFileExample>190191Apply the whole directory:192193```bash CLI194ant apply .195```196197`claude-lock.json` then has an entry for every file in the project.198199Relative paths are how these files point at each other. `ant apply` pins agent and skill references to the version it just applied, so editing `reviewer.md` or the skill updates everything that references them in the same run. A path also works inside an object, as in the deployment's `resources` entry, where the other keys such as `access` are kept.200201To point at a resource these files don't manage, write its ID (`agent_...`, `skill_...`) instead. Anything else, such as `{type: anthropic, skill_id: xlsx}`, is sent to the API as written. A skill reference can also be a GitHub URL of the form `https://github.com/<owner>/<repo>/tree/<branch>/<dir>`, for example a directory of Anthropic's open-source [skills repository](https://github.com/anthropics/skills): `ant apply` downloads and uploads that directory, pinned to the resolved commit until you run with `--upgrade` (set `GITHUB_TOKEN` for a private repository).202203### How ant apply infers a file's kind204205When `ant apply` walks a directory, it determines each file's kind from the first of these that matches:2062071. A top-level `type` field in the file.2082. The directory the file is directly in: `agents/`, `environments/`, `memory_stores/`, or `deployments/`.2093. A file name that starts with the kind, such as `environment_staging.md`.210211It skips files that match none of these, such as READMEs and CI configuration, unless you name them on the command line. A named Markdown file that matches none is treated as an agent, and a named YAML or JSON file that matches none is an error.212213## Edit and reapply214215Running `ant apply` with no arguments reconciles every file the lockfile tracks. At a terminal, it also lists untracked resource files under the lockfile's directory and offers to add them. Deleting a field from a file clears it on the resource if the API allows that field to be cleared. A field you never set, or one the API can't clear, keeps its current value.216217If a resource was edited, archived, or deleted outside these files (in the Claude Console, for example), the plan ends with `This plan cannot be applied:` and the reason. The command then exits with `refusing to apply`. Pass `--force` to overwrite the edit or create a replacement.218219Deleting a file leaves its resource in place with a warning, and `--prune` removes it (archiving it, or deleting it for a skill). Renaming a file therefore declares a new resource and leaves the old one in place until you prune.220221`ant apply` can't adopt a resource you created in the Console or with `ant beta:agents create`. Only what's in the lockfile is managed, and applying a file that describes an existing agent creates a second one. If you downloaded your agent from the Console with **Export as code**, the download includes its own `claude-lock.json`, so applying it updates the resources you built there.222223## Run ant apply in CI224225Without a terminal, `ant apply` prints the plan and stops with `cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only`. Set up CI as follows:226227* Run `ant apply --yes .` on your default branch after merge, naming the project directory. A bare `ant apply --yes` reconciles only files the lockfile already tracks and skips a newly added one.228* On pull requests, run `ant apply --dry-run .` to print the plan for reviewers. It's informational only and exits 0 even when the plan is blocked.229* Commit the updated `claude-lock.json` at the end of the job, even when the apply step failed partway, because a partial apply still records what it created.230* Run one apply at a time, because nothing locks the lockfile.231* Authenticate with [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) rather than a stored API key, as an identity that reaches the organization and workspace recorded in `claude-lock.json`. `ant apply` refuses credentials that resolve to any other organization or workspace.232233For a complete GitHub Actions workflow, see the [CI example in the CLI README](https://github.com/anthropics/anthropic-cli#in-ci).234235## Flags236237| Flag | Effect |238| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |239| `--dry-run` | Print the plan and exit without applying or writing the lockfile. Exits 0 even when the plan is blocked. |240| `--yes` | Apply without asking for confirmation. Required when there's no terminal. |241| `--force` | Apply even where a resource was changed, archived, or deleted outside these files. |242| `--prune` | Remove resources that are in the lockfile but no longer declared in a file. |243| `--upgrade` | Re-resolve skills referenced by GitHub URL, which otherwise stay pinned to the commit recorded in the lockfile. |244| `--lock-file <path>` | Use this lockfile instead of searching upward from the current directory. Keep one for each organization or workspace: `ant apply` refuses a lockfile whose organization or workspace doesn't match your credentials. |245| `--verbose`, `-v` | Show unchanged resources and full field values in the plan. |246247## Next steps248249<CardGroup cols={3}>250 <Card title="Start a session" icon="terminal" href="https://platform.claude.com/docs/en/managed-agents/sessions">251 Run the agents you applied, from the CLI or an SDK252 </Card>253254 <Card title="Scheduled deployments" icon="clock" href="https://platform.claude.com/docs/en/managed-agents/scheduled-deployments">255 Deployment fields, run history, and pausing256 </Card>257258 <Card title="CLI scripting and automation" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/scripting">259 Scripting patterns and use from Claude Code260 </Card>261</CardGroup>262