skip to content

What do Claude Code's --settings and --setting-sources launch flags each do, and how do they interact with managed settings?

level: middleimportance: nice to knowfreq 6%

answer

  1. one adds, one filters
  2. a layer for this session only
  3. omitted keys keep file values
  4. user, project, local as a list
  5. the organization's layer still applies

basics

~20 s

--settings adds JSON values for one session above the user, project and local files but below managed settings, merging key by key. --setting-sources chooses which of user, project and local files load; managed settings still load.

solid answer

~40 s

`--settings` takes a JSON file path or inline JSON and applies it at the command-line level for one session: above `~/.claude/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`, below managed. It merges key by key, so omitted keys keep their file values, and it writes nothing to disk. It can set what the user file can set, not managed-only or global config keys. `--setting-sources` is a filter, not a layer: a comma-separated list of `user`, `project` and `local` naming which files load, so `--setting-sources user` skips the repository's settings and `.mcp.json`. Neither flag removes managed settings, which keep the final word apart from a few security keys.

code

bash · 8 lines
bash
# Try a value for one session without saving it
claude --settings '{"spinnerTipsEnabled": true}'

# Read only your user settings, skipping the repository's .claude files
claude --setting-sources user

# User and project files only, plus a pinned overlay file
claude --setting-sources user,project --settings ./review-settings.json

go deeper

for a junior

Recall that --settings applies values for one session without saving them and that --setting-sources lists which settings files load.

for a middle

Explain where --settings sits in the precedence stack, that it merges key by key, and that --setting-sources filters files rather than adding a level.

for a senior

Use the pair deliberately: skipping a repository's settings and servers on an unfamiliar codebase, forcing a value the project file would override, and reproducing a teammate's setup.

for a principal

Judge when launch flags are enough for automation or review jobs and when an organization needs managed settings because flags are optional and per-invocation.

## Two flags, two jobs Claude Code has two launch flags that shape which settings a session sees without touching any file: - **`--settings <file-or-json>`** adds a **layer** of settings for this session. - **`--setting-sources <list>`** chooses which of your **settings files** load at all. They answer different questions — "what extra values?" versus "which files?" — and they combine. ## --settings: a one-session layer `--settings` takes either a path to a JSON file or an inline JSON string. Its values sit at the **command line** level of the precedence stack: above `~/.claude/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`, below managed settings. Key behaviours: 1. **It merges key by key.** A key you set in `--settings` overrides the same key in your files for this session; a key you omit keeps its file value. It is not a replacement configuration. 2. **List keys still merge**, exactly as between files. 3. **It writes nothing.** The next session goes back to your files. 4. **It can set what your user file can set** — not managed-only keys and not global config keys from `~/.claude.json`. 5. **A file path must point to a regular file** no larger than 2 MiB. Because it outranks the project files, `--settings` is how you force a value a repository might otherwise set back. Setting a key in your user file isn't enough when the repository's project settings set the opposite, because the project level sits above the user level. ## --setting-sources: choosing which files load `--setting-sources` takes a comma-separated list of `user`, `project` and `local`. Only the named file levels load: - `--setting-sources user` reads your user file and skips the repository's `.claude/settings.json` and `.claude/settings.local.json` — and its `.mcp.json` too — which is a sensible start on a repository you didn't write. - `--setting-sources user,project` skips your personal local file for a reproducible run. - Excluding `project` also skips the project's `.claude/rules` files, and excluding `local` skips `CLAUDE.local.md`. ## Managed settings stay on top Neither flag removes the organization's layer: | Question | `--settings` | `--setting-sources` | | :- | :- | :- | | What it does | Adds values for one session | Picks which file levels load | | Precedence | Above user, project, local | Not a level; a filter | | Managed settings | Still win on the same key | Still load | | Writes to disk | No | No | A key that managed settings set can't be overridden by `--settings`, and `--setting-sources` has no value for managed. The only exceptions are the few security keys where a stricter value from a lower level is honoured. ## Other one-session overrides `--settings` is one of three ways to change a value for a single session, and the others don't follow the level stack in the same way: - **A dedicated flag for the key**, such as `--model` for `model` or `--effort` for `effortLevel` and `modelSettings`, overrides the key for that session regardless of which file set it. - **A paired environment variable**, such as `ANTHROPIC_MODEL` for `model`, is decided per pair; each key's entry in the settings reference says which source Claude Code reads first. - **`--settings`** works for any key the user file can hold, and is the general-purpose option when a key has no flag of its own. A related launch flag, `--restricted`, goes further than `--setting-sources`: it loads only managed settings and `--settings`, for evaluation harnesses on shared machines where neither the user's nor the project's files should apply. ## Typical uses - Trying a value before committing it: `claude --settings '{"spinnerTipsEnabled": true}'`. - A pinned overlay for a review or automation job checked into a separate path. - Starting on an unfamiliar repository without its committed settings, `env` and servers. - Reproducing a teammate's problem with only the project's files and none of your own. ## Traps - Expecting `--settings` to persist — it doesn't, and `/config` or `/model` are what write defaults. - Expecting `--settings` to replace your files wholesale; omitted keys keep their file values. - Assuming `--setting-sources` without `local` still lets features that save to the local file keep working; switching output style, for example, is refused because the session would never read the value back. - Expecting either flag to escape an organization policy.

  • Your --settings JSON sets one key. What happens to every other key in your files?
    They keep their file-based values. Claude Code merges `--settings` with the settings files by the normal rules: a key set there overrides the same key in local, project or user settings for that session, a key omitted keeps the lower value, and list keys merge. It is an overlay, not a replacement configuration.
  • Why pass --settings to turn a behaviour off instead of setting it in your user file?
    Because the repository's project settings sit above your user file and can set the value back. `--settings` is at the command-line level, above every file except managed, so it wins over the project for that session — the reason it is used to force a safe value on a repository you didn't write.

  • --settings saves its values into ~/.claude/settings.json
  • --settings replaces every settings file for the session
  • --setting-sources can leave out managed settings for one session
  • --settings can set global config keys such as autoConnectIde