apply changedcli-sdks-libraries/cli/apply
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+20added
Lines−20removed
From line
33
where the diff opens
First seen
4 Sep 2026
this site's first read of the page
Recorded edits11to this page, all time
### How ant apply infers a file’s kind ### How ant apply infers a file's kind
The whole hunk
from line 33, old and new numbered
/
from line 33
3333 </CodeGroupItem>
3434</CodeGroup>
3535
36The 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.
36The 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.
3737
3838In an interactive terminal, `ant apply` prints the plan and waits for your approval:
3939
from line 93
9393}
9494```
9595
96Commit 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 detects an edited file, or a resource changed outside these files.
96Commit 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 detects an edited file, or a resource changed outside these files.
9797
9898## Grow it into a project
9999
100You 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:
100You 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:
101101
102102* An [environment](https://platform.claude.com/docs/en/managed-agents/environments) is a YAML file in `environments/`.
103103* A [memory store](https://platform.claude.com/docs/en/managed-agents/memory) is a YAML file in `memory_stores/`.
from line 105
105105* 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.
106106* A [vault](https://platform.claude.com/docs/en/managed-agents/vaults) is a YAML file in `vaults/` whose only fields are `display_name` and, optionally, `metadata`. Vault files need CLI version 1.34.0 or later.
107107
108Any 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. A vault has no text field, so `ant apply` refuses a vault Markdown file that has prose.
108Any 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. A vault has no text field, so `ant apply` refuses a vault Markdown file that has prose.
109109
110Resources 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 agent in `agents/lead.md` lists `./reviewer.md` under `multiagent.subagents.predefined_agents`, 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. A path under `multiagent.subagents.predefined_agents` or `multiagent.workflows.predefined_agents` needs CLI version 1.40.0 or later. The project has six files:
110Resources 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 agent in `agents/lead.md` lists `./reviewer.md` under `multiagent.subagents.predefined_agents`, 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. A path under `multiagent.subagents.predefined_agents` or `multiagent.workflows.predefined_agents` needs CLI version 1.40.0 or later. The project has six files:
111111
112112<FileExplorer>
113113 <File filename="agents/reviewer.md">
from line 204
204204
205205`claude-lock.json` then has an entry for every file in the project.
206206
207Relative 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.
207Relative 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.
208208
209To 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).
209To 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).
210210
211A path can also be a glob. Under `skills`, a glob references every skill it matches and skips anything else it matches, such as a README. Under an agent's `tools`, a path or glob names YAML or JSON files instead of resources: `ant apply` inserts each file's contents, one tool or a list of tools, into the list at that position. Put those files in a subdirectory such as `agents/tools/`, because `ant apply` refuses to insert a file that it would also read as an agent. A path or glob that matches nothing is an error.
211A path can also be a glob. Under `skills`, a glob references every skill it matches and skips anything else it matches, such as a README. Under an agent’s `tools`, a path or glob names YAML or JSON files instead of resources: `ant apply` inserts each file’s contents, one tool or a list of tools, into the list at that position. Put those files in a subdirectory such as `agents/tools/`, because `ant apply` refuses to insert a file that it would also read as an agent. A path or glob that matches nothing is an error.
212212
213213```markdown agents/reviewer.md
214214---
from line 242
242242}
243243```
244244
245### How ant apply infers a file's kind
245### How ant apply infers a file’s kind
246246
247When `ant apply` walks a directory, it determines each file's kind from the first of these that matches:
247When `ant apply` walks a directory, it determines each file’s kind from the first of these that matches:
248248
2492491. A top-level `type` field in the file.
2502502. The directory the file is directly in: `agents/`, `environments/`, `memory_stores/`, `deployments/`, or `vaults/`.
from line 255
255255
256256## Edit and reapply
257257
258Running `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.
258Running `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.
259259
260260If 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.
261261
262262Deleting 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.
263263
264`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.
264`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.
265265
266266## Run ant apply in CI
267267
from line 268
268268Without 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:
269269
270270* 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.
271* 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.
271* 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.
272272* 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.
273273* Run one apply at a time, because nothing locks the lockfile.
274274* 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.
from line 320
320320
321321Run the first `ant apply` on your machine and commit `claude-lock.json` before you turn the workflow on. The last step commits changes only to a lockfile that Git already tracks.
322322
323To create the federation rule and service account that the `env` block names, see [Use WIF with GitHub Actions](https://platform.claude.com/docs/en/manage-claude/wif-providers/github-actions). Enable the rule for a single workspace, the one recorded in `claude-lock.json`, so that the token exchange doesn't need a workspace ID. Because the job names an environment, its identity token's `sub` claim is `repo:<owner>/<repo>:environment:agents-prod`, so that's the value the rule's `subject_prefix` must match.
323To create the federation rule and service account that the `env` block names, see [Use WIF with GitHub Actions](https://platform.claude.com/docs/en/manage-claude/wif-providers/github-actions). Enable the rule for a single workspace, the one recorded in `claude-lock.json`, so that the token exchange doesn’t need a workspace ID. Because the job names an environment, its identity token’s `sub` claim is `repo:<owner>/<repo>:environment:agents-prod`, so that’s the value the rule’s `subject_prefix` must match.
324324
325325## Flags
326326
from line 327
327327| Flag | Effect |
328328| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
329329| `--dry-run` | Print the plan and exit without applying or writing the lockfile. Exits 0 even when the plan is blocked. |
330| `--yes` | Apply without asking for confirmation. Required when there's no terminal. |
330| `--yes` | Apply without asking for confirmation. Required when there’s no terminal. |
331331| `--force` | Apply even where a resource was changed, archived, or deleted outside these files. |
332332| `--prune` | Remove resources that are in the lockfile but no longer declared in a file. |
333333| `--upgrade` | Re-resolve skills referenced by GitHub URL, which otherwise stay pinned to the commit recorded in the lockfile. |
334| `--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. |
334| `--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. |
335335| `--verbose`, `-v` | Show unchanged resources and full field values in the plan. |
336336
337337## Next steps
No line in this hunk matches that.