[DOCS] Settings precedence list omits environment variables, which override command-line flags

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

Settings precedence order

What the docs currently say

The settings page gives an explicit precedence list:

When the same setting appears in multiple scopes, Claude Code applies them in priority order: 1. Managed (highest): can't be overridden by anything 2. Command line arguments: temporary session overrides 3. Local: overrides project and user settings 4. Project: overrides user settings 5. User (lowest): applies when nothing else specifies the setting

Environment variables do not appear anywhere in this list. Reading it, a user would reasonably conclude that command-line arguments sit second from the top and are overridden only by managed settings.

The effortLevel entry mentions both mechanisms but doesn't rank them against each other:

effortLevel: … --effort and CLAUDE_CODE_EFFORT_LEVEL override this for one session.

Both are described as overriding the settings file. What happens when the two disagree isn't stated.

What actually happens

The environment variable wins over the command-line flag. Demonstrated with effort, where the effective value is observable through a side effect (effort max triggers a known 400 on WebSearch for this model, while high does not):

# env var set to high, flag set to max
CLAUDE_CODE_EFFORT_LEVEL=high claude --effort max --model claude-opus-5 \
  -p "Call the WebSearch tool with query='example domain'." --allowedTools WebSearch
# -> succeeds  (i.e. effort=high was used; the --effort max flag had no effect)

# same flag, env var cleared
env -u CLAUDE_CODE_EFFORT_LEVEL claude --effort max --model claude-opus-5 \
  -p "Call the WebSearch tool with query='example domain'." --allowedTools WebSearch
# -> API Error: 400 output_config.effort 'max' is not supported ...
#    (i.e. effort=max was used)

Claude Code 2.1.219. The only difference between the two runs is whether the environment variable is set.

Why this matters

The flag is ignored silently. There's no warning that --effort max had no effect, and the run looks like a successful pass. This is the opposite of the usual CLI convention, where an explicit flag beats ambient environment configuration, so users are unlikely to suspect it.

Concretely: while building a control matrix to isolate a different bug, I recorded --effort max as "passes" for several runs before realising the flag was being ignored because an environment variable was set in my shell. Every one of those rows was wrong. Anyone doing comparative testing — which is exactly what people do when narrowing down a bug to report here — can produce a matrix of false results without any indication that something is off.

Expected

Either:

1. Add environment variables to the precedence list with their actual rank, and state explicitly that they override command-line arguments; or
2. Note it in the effortLevel entry and alongside the other env-var-backed settings.

Option 1 seems better, since the same relationship presumably applies to other settings that have both a flag and an environment variable, and the list is where readers will look for it.

A warning when an explicit flag is overridden by an environment variable would also help, though that's a behaviour change rather than a docs fix.

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)