Using -c to Override a Single Config Key

-c key=value is the escape hatch for the exact situation neither a global config default nor a project-level override handles well: a single, one-off change to exactly one setting, for exactly one invocation, without editing any file or committing to a change that outlives this one run.

Why this exists alongside the config file

The config file — global or per-project — is for what you want to be true by default, repeatedly. -c is for the opposite case: a genuine one-time deviation you don't want to persist anywhere. Editing a config file for a single session's worth of a different setting, and then remembering to edit it back afterward, is exactly the kind of manual bookkeeping -c exists to make unnecessary — set the override on the one invocation that needs it, and every other invocation continues using whatever the file-based defaults already specify.

The exact syntax and what it targets

-c takes a key-value pair matching the same keys the config file itself uses, which means understanding the config file's structure is a prerequisite for using -c correctly — it's not a separate set of options with its own naming convention, it's a direct, single-invocation override of the identical settings the file would otherwise control. Checking the current config reference for exact key names is worth doing here for the same reason it's worth doing when editing the file directly: this is the layer of the CLI most likely to have gained or renamed options since any specific guide, including this one, was last updated.

A concrete case where this is exactly the right tool

Picture your project's config file specifying a comfortable, permissive sandbox default for your everyday work, and one specific session where you want to review something from an unfamiliar source under a much stricter posture — not because your general default is wrong, but because this one task genuinely warrants more caution. -c sandbox_mode=read-only (or whatever the exact key is on your version) on that single invocation gets you the stricter posture for that one session without touching the file that governs every other session in the project.

Why this is safer than temporarily editing the file

A file edit made "temporarily" and meant to be reverted afterward is a classic source of configuration drift — the kind of change that's easy to forget to undo, especially if something else comes up right after the session that prompted it. A -c override applied only to a single invocation structurally can't outlive that invocation; there's no revert step to forget, because nothing persistent was ever changed in the first place.

Combining multiple overrides on one invocation

Where the CLI supports specifying -c more than once on a single command, multiple settings can be overridden simultaneously for one particularly unusual invocation — worth checking your version's actual syntax for how repeated -c flags combine, rather than assuming a specific behavior, since this is exactly the kind of detail worth a quick confirmation before relying on it for something that matters.

When reaching for -c signals you actually want a project-level default instead

If you find yourself passing the same -c override on every single invocation within a specific project, that's a signal the override has stopped being a one-off exception and has become, in practice, that project's actual default — and it belongs in a project-level config file instead, not repeated manually as a flag every time. Recognizing this shift and promoting a repeated override into an actual persistent setting removes the ongoing manual repetition -c was never meant to replace indefinitely.

Scripting with -c for controlled, repeatable variation

For a script that needs to run Codex with a specific, deliberately-varied setting different from whatever the ambient config specifies — testing behavior across several different sandbox modes, say — -c is the mechanism that lets a script control exactly what it needs without depending on or modifying whatever config file happens to be present on the machine it runs on. This makes scripted invocations more portable and predictable, since they're not implicitly depending on a config file's contents matching what the script assumes.

The underlying principle this flag represents

-c is a small, narrow feature, and its value is exactly proportional to how precisely scoped it is — a single key, a single invocation, no persistent side effect. That narrowness is the feature, not a limitation: it's the tool for exactly the cases where you want a deviation to be as contained and as easy to reason about as possible, rather than reaching for a broader, more persistent mechanism for something that was only ever meant to apply once.

A quick mental checklist for choosing the right layer

Faced with wanting to change some setting, it's worth running through the three layers in order of persistence: does this need to be true for every project, every session, indefinitely — that's the global config file. Does it need to be true for one specific project, every session within it — that's a project-level override. Does it need to be true for exactly this one invocation, right now, and nowhere else — that's -c. Picking the layer that actually matches the scope of the change you want avoids both under-scoping a change that should have been persistent and over-scoping one that should have stayed a one-off.

Documenting a -c override used in a shared script

If a -c override appears inside a script other people on your team will run, it's worth a short comment explaining why that specific override is there — a teammate reading the script later, wondering why it deviates from the ambient defaults, shouldn't have to guess whether the override was deliberate or an artifact left over from debugging something unrelated.