--settings vs --setting-sources
People think --settings and --setting-sources do one job, and they do not. --settings adds one more layer of settings from a file or a string, and its values win over your files. --setting-sources picks which of your own files load at all: user, project or local. A CI run often uses both.
--settings Flag
It loads extra settings for one session from JSON.
--settings loads extra settings for this session, from a JSON file or a JSON string. Its values win over the same keys in your settings.json files. Keys it leaves out keep their usual values. Your admin's managed settings still win over it. The file must be a normal file of 2 MiB or less.
--setting-sources Flag
It picks which settings files Claude Code reads.
--setting-sources picks which settings files Claude Code reads: user, project, local, or a mix with commas. A CI job can skip a person's own user settings. Then each run acts the same. Sessions this one starts, such as background sessions and teammates, keep the same list.
In one line
- --settings Flag
- It loads extra settings for one session from JSON.
- --setting-sources Flag
- It picks which settings files Claude Code reads.