--settings
A Claude Code CLI flag, read out of the shipped bundle. It has been in the build since v2.1.138, including the newest one read.
Path to a settings JSON file or an inline JSON string. Values you set here override the same keys in your settings.json files for this session. Keys you omit keep their file-based values. The file must be a regular file no larger than 2 MiB. See settings precedence
Anthropic's own wording. Read off CLI reference, captured 2026-09-26.
In the changelogs
57Releases whose published page names --settings.
-
v2.1.307
Disabling all plugins now skips policy plugins and explains what stays on
Disabling all plugins now leaves policy-enforced plugins alone and says when
--settingskeeps plugins on for this sessionfound in this entry's text
-
v2.1.307
Clearer messages for plugins your organization or --settings keeps on
Changing a plugin your organization's policy turns on is now refused, and a plugin kept on by
--settingsis shown as still enabled this sessionnamed in this entry, found in this entry's text
-
v2.1.304
Option to switch on skills or MCP servers now reads "Turn them on"
A dialog option once labelled "Enable for this session" now reads "Turn them on", and --settings errors name inline JSON
found in this entry's text
-
v2.1.300
Update restart is refused if a launch settings file is gone
Claude Code will not restart a session onto a new version if a file passed with --settings or --mcp-config can no longer be read
found in this entry's text, named in this entry
-
v2.1.296
Claude Code now explains why your hooks are not running
Claude Code shows notices saying why hooks are off, covering unreadable managed settings, bare mode, safe mode, managed policy and
--settingsfound in this entry's text
-
v2.1.295
Self-hosted runners can pass server-supplied auto mode rules into sessions
A self-hosted runner can write auto mode allow and deny lists from the server into a session's settings, with allow lists held back by default
found in this entry's text
-
v2.1.290
Background workers only keep bypassPermissions mode with consent in your user settings
A background worker in bypassPermissions mode falls back to default unless skipDangerousModePermissionPrompt is true in ~/.claude/settings.json
found in this entry's text
-
v2.1.290
Background sessions ignore
--allow-dangerously-skip-permissionswithout recorded consentBackground sessions now ignore
--allow-dangerously-skip-permissionsunless bypass consent is in your user or policy settingsfound in this entry's text
-
v2.1.288
/login in bare mode explains why it won't sign you in
In bare mode,
/loginnow prints an explanation instead of a sign-in that would have no effectfound in this entry's text
-
v2.1.287
Cloud session hooks panel reworded and gains a plugin hooks section
The panel listing this machine's hooks for a cloud session has shorter text and makes room for a section about plugin hooks
found in this entry's text
-
v2.1.287
Removing a reserved-name plugin marketplace entry now turns its plugins off safely
claude plugin marketplace removenow turns off affected plugins first, and plugin settings and secrets are copied when you switch pluginsfound in this entry's text
-
v2.1.287
Project settings can no longer change auto-update for the official marketplace
Auto-update for the official plugin marketplace is now read only from user,
--settingsand managed settings, not from project filesfound in this entry's text
-
v2.1.285
New --desktop flag, and background commands now accept options in front of them
--desktopopens the Claude Desktop app and now errors when combined with background or worktree optionsfound in this entry's text
-
v2.1.285
New descriptions of how settings files combine for sandbox rules
New text explains that project settings cannot re-open paths denied for reading, and that some project-level network values are ignored
found in this entry's text, named in this entry
-
v2.1.285
Sandbox ignores some project-level file access grants
Project and local settings can no longer widen sandbox file access when an admin requires the sandbox or the path is under a denied read path
found in this entry's text
-
v2.1.285
Sandbox lock on unsandboxed commands now described as covering your own settings
overrides_lockedis now described as true whenallowUnsandboxedCommands: falsecomes from a--settingsfile or user settingsfound in this entry's text
-
v2.1.285
Sandbox settings carry clearer descriptions
Descriptions for sandbox settings are fuller, including that sandbox.enabled defaults to false; behaviour is unchanged
found in this entry's text
-
v2.1.284
Settings files outside ~/.claude can't be symlinks to a network location
A settings file outside Claude Code's config folder that is a symlink pointing to a network path is now refused with
ERR_SYMLINK_TO_NETWORK_PATHfound in this entry's text
-
v2.1.284
--settingsfollows links before loading and explains why a file is refusedA file passed to
--settingsis resolved through links and case first, and a refused file gets an error naming the path and the reasonfound in this entry's text, named in this entry
-
v2.1.282
Repositories can no longer exempt commands from a sandbox an admin has locked down
When running commands outside the sandbox is forbidden,
sandbox.excludedCommandsentries in a project's own settings files are ignoredfound in this entry's text
-
v2.1.282
Auto-compact preference now carries over to launched sessions
Sessions launched by Claude Code now receive your auto-compact setting along with its other passed-on settings
found in this entry's text, named in this entry
-
v2.1.282
Remote Control project-thread sessions now run with auto-compact turned on
Sessions that Remote Control starts for a project thread can now be launched with auto-compact forced on, controlled by a remote switch that is on by default
found in this entry's text, named in this entry
-
v2.1.281
Settings-file edit guard adds desktop-app, symlink and managed-policy refusal messages, but the path is off in this build
Refusal messages for settings-file edits via the desktop app, symlinks or managed policy exist but cannot run in this build
found in this entry's text
-
v2.1.281
Hidden --managed-settings flag added to
claude agentsand forwarded to dispatched sessionsclaude agentsgains a hidden--managed-settings <json>option that is passed on to sessions it startsfound in this entry's text
-
v2.1.281
--tmux worktree relaunch absolutizes path arguments
When --tmux relaunches Claude Code for a worktree, relative file paths in flags are now turned into full paths
found in this entry's text
-
v2.1.281
claude agentsview now honours --settings, --managed-settings and setting sourcesclaude agentsnow applies--settings,--managed-settingsand--setting-sourcesfound in this entry's text, named in this entry
-
v2.1.281
Sandbox survives an invalid settings change instead of failing
A bad sandbox settings change now keeps the running sandbox config, and a failed first build retries on the next settings change
found in this entry's text
-
v2.1.281
SDK/CLI --managed-settings payload is now loaded at startup alongside --settings
The
--managed-settingspayload, including the SDK'smanagedSettingsoption, is now actually loaded at startupfound in this entry's text, named in this entry
-
v2.1.281
--managed-settingsis carried through to spawned sessions;--setting-sourcesis accepted and discarded by one argument parser--managed-settings is now passed on to sessions Claude Code starts itself, while one parser reads --setting-sources and throws the value away
found in this entry's text
-
v2.1.281
bg dispatch carries reattachEnv and retries while the daemon starts
Background dispatch now retries while the daemon starts, carries a reattach environment, and forwards flags like
--settingswhen attachingfound in this entry's text
-
v2.1.281
Sandbox init failure tells you to fix the settings, not just restart
When required sandbox settings fail to build, the error now tells you to fix the settings to retry, and to restart only if a
--settingsfile is pinnedfound in this entry's text
-
v2.1.271
Bridge child auto-mode permission defaulting, gated off
Bridge-spawned child sessions may be defaulted to auto permission mode, gated off
found in this entry's text
-
v2.1.271
New CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS bridge env var
New CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS bridge env var, plus a new auto settings argument on worker resume
found in this entry's text
-
v2.1.269
Plugin-provided /config settings now show their plugin source and can be locked by managed settings
/config now shows which plugin a setting comes from, and organizations can lock those settings
found in this entry's text
-
v2.1.267
Managed-settings-only
secDefaultflag controls seating of the bundled sec-default pluginA new managed-settings-only flag lets organizations put their bundled sec-default plugin ahead of user-installed plugin hooks
found in this entry's text
-
v2.1.260
Remote Control machine-profile sharing setting
A new setting controls how much machine info Remote Control shares when it registers a device.
found in this entry's text
-
v2.1.259
remoteTools.allowUnattendedServing setting formalized in schema
The settings schema documents remoteTools.allowUnattendedServing, and project, local and --settings values are ignored for it.
found in this entry's text, named in this entry
-
v2.1.257
allowManagedPermissionRulesOnly semantics clarified/expanded
The allowManagedPermissionRulesOnly description now spells out exactly which rule sources it ignores and which still apply.
found in this entry's text
-
v2.1.248
New
--restrictedsession modeNew --restricted flag starts a locked-down session with no shell tools and no settings files.
found in this entry's text
-
v2.1.247
Cloud working-tree upload refuses when git is missing or when project settings steer git
Cloud upload refuses when git is missing or your project settings set git-related environment variables.
named in this entry, found in this entry's text
-
v2.1.247
Configurable spinner tips: file-loaded, object-shaped, with a custom label
spinnerTipsOverride now takes an object: load tips from a file, relabel them, and drop the built-ins.
found in this entry's text
-
v2.1.246
Model cost overrides are documented as honoured from a managing host application
Model cost overrides are now documented as also accepted from a host app managing the provider.
found in this entry's text
-
v2.1.242
disableArtifactdeprecated in favour ofenableArtifactUse enableArtifact instead of disableArtifact, which now only counts when set to true.
found in this entry's text
-
v2.1.242
Cloud-hosted sessions now refuse local CLI options instead of quietly dropping them
Running with --cloud now tells you which local CLI options were ignored or refused, and why.
found in this entry's text
-
v2.1.242
New
modelPickersetting curates the /model listA new modelPicker setting curates or replaces the model list you see in /model.
found in this entry's text
-
v2.1.242
New
modelPricingmanaged setting bills usage at contracted ratesOrganizations can bill your reported spend at contracted rates everywhere costs appear.
found in this entry's text
-
v2.1.242
Consent screen explaining what forwarding your hooks to a cloud session means
A consent screen explains what letting cloud sessions run your local hooks means.
found in this entry's text
-
v2.1.234
New
syncClaudeAiSkillssetting turns off skills synced from your claude.ai accountYou can stop Claude Code downloading skills from your claude.ai account with one setting.
found in this entry's text
-
v2.1.232
sandbox.ripgrepis ignored when set by project settingsA repo's settings can no longer point sandboxed search at an arbitrary ripgrep binary.
named in this entry, found in this entry's text
-
v2.1.229
Settings fix prompt notes that --settings is read once
Fixes to a file passed via
--settingsare noted as taking effect next session.named in this entry, found in this entry's text
-
v2.1.229
Self-hosted runner accepts a settings file, and rejects hooks and orchestrator mode on Windows
The runner can pass a settings file to sessions; its Windows hooks guard never actually fires.
named in this entry, found in this entry's text
-
v2.1.224
Sandbox credential masking gains JWT handling, per-claim masking and AWS SigV4 re-signing
Sandbox credential masking can fake JWTs, mask single claims, and re-sign AWS requests after swapping keys.
found in this entry's text
-
v2.1.219
New sandbox setting: network.strictAllowlist
Set strictAllowlist to have the sandbox flat-out deny hosts outside your allowed domains instead of prompting.
named in this entry, found in this entry's text
-
v2.1.181
sandbox.allowAppleEventsSetting (macOS)found in this entry's text
-
v2.1.140
Marketplace
autoUpdateSynced from Settingsfound in this entry's text
-
v2.1.133
Clearer Plugin Override Warnings
found in this entry's text
-
v1.0.94
Settings Processing
found in this entry's text
First cited
8The earliest release whose published evidence quoted --settings was v2.1.232, 13 Aug 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
2 further spans in the ledger name it. The list above is the earliest first and stops at 6.
Presence across releases
1Build by build
149One row per release since the first build this name was read out of. Absent means the build was read and the name was not in it, never mined means no bundle for that release was ever archived, and a declared type or a default is only ever what that release's own bundle stated.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.