{"name":"--settings","slug":"settings","family":"cli","title":"CLI flags","noun":"CLI flag","description":"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](\/docs\/en\/settings#settings-precedence)","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":"2.1.138","removed_in":null,"in_current_build":true,"newest_mined":"2.1.308","builds":149,"mined_builds":149,"first_cited":{"version":"2.1.232","released_at":"2026-08-13 21:30:53","spans":8}},"aliases":[],"entries":[{"version":"2.1.307","anchor":"plugin-disable-all-now-accounts-for-policy-managed-plugins-a","heading":"Disabling all plugins now skips policy plugins and explains what stays on","line":"Disabling all plugins now leaves policy-enforced plugins alone and says when `--settings` keeps plugins on for this session","released_at":"2026-10-21 20:47:18","reason":"found in this entry's text"},{"version":"2.1.307","anchor":"plugins-policy-enabled-plugins-dependency-closure-and-se","heading":"Clearer messages for plugins your organization or --settings keeps on","line":"Changing a plugin your organization's policy turns on is now refused, and a plugin kept on by `--settings` is shown as still enabled this session","released_at":"2026-10-21 20:47:18","reason":"named in this entry, found in this entry's text"},{"version":"2.1.304","anchor":"skillmcp-prompt-changes-dialog-label-and-settings-label","heading":"Option to switch on skills or MCP servers now reads \"Turn them on\"","line":"A dialog option once labelled \"Enable for this session\" now reads \"Turn them on\", and --settings errors name inline JSON","released_at":"2026-10-19 19:47:15","reason":"found in this entry's text"},{"version":"2.1.300","anchor":"update-restart-refused-when-launch-settings-mcp-config-f","heading":"Update restart is refused if a launch settings file is gone","line":"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","released_at":"2026-10-14 14:27:26","reason":"found in this entry's text, named in this entry"},{"version":"2.1.296","anchor":"new-hooks-disabled-notices-for-unreadable-managed-settings","heading":"Claude Code now explains why your hooks are not running","line":"Claude Code shows notices saying why hooks are off, covering unreadable managed settings, bare mode, safe mode, managed policy and `--settings`","released_at":"2026-10-09 16:58:10","reason":"found in this entry's text"},{"version":"2.1.295","anchor":"self-hosted-runner-can-forward-server-auto-mode-lists-into-s","heading":"Self-hosted runners can pass server-supplied auto mode rules into sessions","line":"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","released_at":"2026-10-08 18:22:58","reason":"found in this entry's text"},{"version":"2.1.290","anchor":"background-worker-bypass-permission-mode-requires-consent-in","heading":"Background workers only keep bypassPermissions mode with consent in your user settings","line":"A background worker in bypassPermissions mode falls back to default unless skipDangerousModePermissionPrompt is true in ~\/.claude\/settings.json","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text"},{"version":"2.1.290","anchor":"background-sessions-ignore-allow-dangerously-skip-permissi","heading":"Background sessions ignore --allow-dangerously-skip-permissions without recorded consent","line":"Background sessions now ignore `--allow-dangerously-skip-permissions` unless bypass consent is in your user or policy settings","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text"},{"version":"2.1.288","anchor":"bare-mode-login-now-refuses-with-explanation","heading":"\/login in bare mode explains why it won't sign you in","line":"In bare mode, `\/login` now prints an explanation instead of a sign-in that would have no effect","released_at":"2026-10-02 18:30:40","reason":"found in this entry's text"},{"version":"2.1.287","anchor":"cloud-session-hooks-panel-reworded-and-gains-plugin-hooks-se","heading":"Cloud session hooks panel reworded and gains a plugin hooks section","line":"The panel listing this machine's hooks for a cloud session has shorter text and makes room for a section about plugin hooks","released_at":"2026-10-01 16:59:25","reason":"found in this entry's text"}],"entries_total":57,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"claude-code","path":"agent-teams","title":"Orchestrate teams of Claude Code sessions","documented":false},{"source":"claude-code","path":"agent-view","title":"Manage multiple agents with agent view","documented":false},{"source":"claude-code","path":"artifacts","title":"Share session output as artifacts","documented":false},{"source":"claude-code","path":"auto-mode-config","title":"Configure auto mode","documented":false},{"source":"claude-code","path":"changelog","title":"Claude Code changelog","documented":false},{"source":"claude-code","path":"claude-apps-gateway-on-aws","title":"Deploy Claude apps gateway on AWS","documented":false},{"source":"claude-code","path":"claude-directory","title":"Explore the .claude directory","documented":false},{"source":"claude-code","path":"commands","title":"Commands","documented":false},{"source":"claude-code","path":"costs","title":"Manage costs effectively","documented":false}],"docs_total":13,"gates":[],"related":[],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/settings","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}