Run Claude Code programmatically changedheadless
Nearest release: v2.1.283, published 4 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 25 Sep 2026 23:42 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 28 Sep 2026 23:37 UTC.
Upstream edited
Recorded here
Lines+33added
Lines−33removed
From line
46
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
The whole hunk
from line 46, old and new numbered
/
from line 46
4646
4747In bare mode Claude has access to the Bash, file read, and file edit tools. Pass any context you need with a flag:
4848
49| To load | Use |
50| ----------------------- | ------------------------------------------------------- |
49| To load | Use |
50| - | - |
5151| System prompt additions | `--append-system-prompt`, `--append-system-prompt-file` |
52| Settings | `--settings <file-or-json>` |
53| MCP servers | `--mcp-config <file-or-json>` |
54| Custom agents | `--agents <json>` |
55| A plugin | `--plugin-dir <path>`, `--plugin-url <url>` |
52| Settings | `--settings <file-or-json>` |
53| MCP servers | `--mcp-config <file-or-json>` |
54| Custom agents | `--agents <json>` |
55| A plugin | `--plugin-dir <path>`, `--plugin-url <url>` |
5656
5757<Note>
5858 `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.
from line 200
200200
201201When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. On v2.1.246 or later, when a `401` or `403` rejects an [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) credential, Claude Code makes the first two retries quietly with no event, then emits the event as usual from the third consecutive retry onward. The quiet retries still count toward `attempt`. You can use the event to show retry progress in your own interface.
202202
203| Field | Type | Description |
204| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
205| `type` | `"system"` | message type |
206| `subtype` | `"api_retry"` | identifies this as a retry event |
207| `attempt` | integer | current attempt number, starting at 1 |
208| `max_retries` | integer | total retries permitted for this failure's cause, which can be fewer than the session-wide budget |
209| `retry_delay_ms` | integer | milliseconds until the next attempt |
210| `error_status` | integer or null | HTTP status code of the failed attempt, or `null` when the attempt got no HTTP response from the API |
211| `no_response` | object, optional | present only when the failed attempt got [no response headers in time](/docs/en/errors#no-response-from-api). `waited_ms` is how long that attempt waited and `retry_wait_ms` is how long the retry will wait. In these events, `max_retries` reflects the one retry this cause normally gets, not the session-wide budget. Requires Claude Code v2.1.261 or later |
212| `error` | string | error category: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, or `unknown` |
213| `uuid` | string | unique event identifier |
214| `session_id` | string | session the event belongs to |
203| Field | Type | Description |
204| - | - | - |
205| `type` | `"system"` | message type |
206| `subtype` | `"api_retry"` | identifies this as a retry event |
207| `attempt` | integer | current attempt number, starting at 1 |
208| `max_retries` | integer | total retries permitted for this failure's cause, which can be fewer than the session-wide budget |
209| `retry_delay_ms` | integer | milliseconds until the next attempt |
210| `error_status` | integer or null | HTTP status code of the failed attempt, or `null` when the attempt got no HTTP response from the API |
211| `no_response` | object, optional | present only when the failed attempt got [no response headers in time](/docs/en/errors#no-response-from-api). `waited_ms` is how long that attempt waited and `retry_wait_ms` is how long the retry will wait. In these events, `max_retries` reflects the one retry this cause normally gets, not the session-wide budget. Requires Claude Code v2.1.261 or later |
212| `error` | string | error category: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, or `unknown` |
213| `uuid` | string | unique event identifier |
214| `session_id` | string | session the event belongs to |
215215
216216#### Read session metadata
217217
from line 226
226226
227227Use the plugin fields in the `system/init` event to catch a plugin that didn't load:
228228
229| Field | Type | Description |
230| --------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
231| `plugins` | array | plugins that loaded successfully, each with `name` and `path` |
229| Field | Type | Description |
230| - | - | - |
231| `plugins` | array | plugins that loaded successfully, each with `name` and `path` |
232232| `plugin_errors` | array | plugin load-time errors, each with `plugin`, `type`, and `message`. Includes unsatisfied dependency versions and `--plugin-dir` load failures such as a missing path or invalid archive. A plugin that didn't load is absent from `plugins`. The key is omitted when there are no errors |
233233
234234When a `--plugin-dir` directory or archive itself fails to load, its `plugin_errors` entry includes the resolved absolute path as `path`. Use it to tell which of several `--plugin-dir` values failed. The `path` field requires Claude Code v2.1.283 or later.
from line 237
237237
238238Claude Code validates each `--mcp-config` entry at startup and skips entries that fail validation, for example a `url` entry with no `type`. The run continues and exits cleanly, so check these fields to catch a server that never loaded:
239239
240| Field | Type | Description |
241| ------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
242| `mcp_servers` | array | MCP servers in the session, each with `name` and `status` |
240| Field | Type | Description |
241| - | - | - |
242| `mcp_servers` | array | MCP servers in the session, each with `name` and `status` |
243243| `mcp_server_errors` | array | `--mcp-config` entries skipped by config validation, each with `name`, `type`, and `message`. `type` is a skip category such as `unknown_type`, `url_missing_type`, `invalid_config`, or `reserved_name`; treat values you don't recognize as a generic skip. Affected servers are absent from `mcp_servers`. The key is omitted when there are no errors, so a CI gate can fail on a non-empty array. Requires Claude Code v2.1.219 or later |
244244
245245When you run the command by hand in a terminal, Claude Code also prints a startup warning to stderr, such as `Warning: 1 MCP server skipped due to invalid config:`, followed by the reason for each skipped entry. When you redirect stderr, or when a program such as a CI runner or an SDK host captures it, Claude Code prints no warning and reports the skipped entries only in the `mcp_server_errors` field. The warning requires Claude Code v2.1.219 or later.
from line 248
248248
249249When [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/en/env-vars) is set, Claude Code emits `system/plugin_install` events while marketplace plugins install before the first turn. Use these to surface install progress in your own UI.
250250
251| Field | Type | Description |
252| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
253| `type` | `"system"` | message type |
254| `subtype` | `"plugin_install"` | identifies this as a plugin install event |
255| `status` | `"started"`, `"installed"`, `"failed"`, or `"completed"` | `started` and `completed` bracket the overall install; `installed` and `failed` report individual marketplaces |
256| `name` | string, optional | marketplace name, present on `installed` and `failed` |
257| `error` | string, optional | failure message, present on `failed` |
258| `uuid` | string | unique event identifier |
259| `session_id` | string | session the event belongs to |
251| Field | Type | Description |
252| - | - | - |
253| `type` | `"system"` | message type |
254| `subtype` | `"plugin_install"` | identifies this as a plugin install event |
255| `status` | `"started"`, `"installed"`, `"failed"`, or `"completed"` | `started` and `completed` bracket the overall install; `installed` and `failed` report individual marketplaces |
256| `name` | string, optional | marketplace name, present on `installed` and `failed` |
257| `error` | string, optional | failure message, present on `failed` |
258| `uuid` | string | unique event identifier |
259| `session_id` | string | session the event belongs to |
260260
261261### Auto-approve tools
262262
No line in this hunk matches that.