feat: add support for -c/--config to override individual config items (#1137)

This PR introduces support for `-c`/`--config` so users can override
individual config values on the command line using `--config
name=value`. Example:

```
codex --config model=o4-mini
```

Making it possible to set arbitrary config values on the command line
results in a more flexible configuration scheme and makes it easier to
provide single-line examples that can be copy-pasted from documentation.

Effectively, it means there are four levels of configuration for some
values:

- Default value (e.g., `model` currently defaults to `o4-mini`)
- Value in `config.toml` (e.g., user could override the default to be
`model = "o3"` in their `config.toml`)
- Specifying `-c` or `--config` to override `model` (e.g., user can
include `-c model=o3` in their list of args to Codex)
- If available, a config-specific flag can be used, which takes
precedence over `-c` (e.g., user can specify `--model o3` in their list
of args to Codex)

Now that it is possible to specify anything that could be configured in
`config.toml` on the command line using `-c`, we do not need to have a
custom flag for every possible config option (which can clutter the
output of `--help`). To that end, as part of this PR, we drop support
for the `--disable-response-storage` flag, as users can now specify `-c
disable_response_storage=true` to get the equivalent functionality.

Under the hood, this works by loading the `config.toml` into a
`toml::Value`. Then for each `key=value`, we create a small synthetic
TOML file with `value` so that we can run the TOML parser to get the
equivalent `toml::Value`. We then parse `key` to determine the point in
the original `toml::Value` to do the insert/replace. Once all of the
overrides from `-c` args have been applied, the `toml::Value` is
deserialized into a `ConfigToml` and then the `ConfigOverrides` are
applied, as before.

codex-rs/cli/src/debug_sandbox.rs

@@ -1,5 +1,6 @@
 use std::path::PathBuf;
 
+use codex_common::CliConfigOverrides;
 use codex_common::SandboxPermissionOption;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
@@ -20,12 +21,14 @@ pub async fn run_command_under_seatbelt(
     let SeatbeltCommand {
         full_auto,
         sandbox,
+        config_overrides,
         command,
     } = command;
     run_command_under_sandbox(
         full_auto,
         sandbox,
         command,
+        config_overrides,
         codex_linux_sandbox_exe,
         SandboxType::Seatbelt,
     )
@@ -39,12 +42,14 @@ pub async fn run_command_under_landlock(
     let LandlockCommand {
         full_auto,
         sandbox,
+        config_overrides,
         command,
     } = command;
     run_command_under_sandbox(
         full_auto,
         sandbox,
         command,
+        config_overrides,
         codex_linux_sandbox_exe,
         SandboxType::Landlock,
     )
@@ -60,16 +65,22 @@ async fn run_command_under_sandbox(
     full_auto: bool,
     sandbox: SandboxPermissionOption,
     command: Vec<String>,
+    config_overrides: CliConfigOverrides,
     codex_linux_sandbox_exe: Option<PathBuf>,
     sandbox_type: SandboxType,
 ) -> anyhow::Result<()> {
     let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
     let cwd = std::env::current_dir()?;
-    let config = Config::load_with_overrides(ConfigOverrides {
-        sandbox_policy: Some(sandbox_policy),
-        codex_linux_sandbox_exe,
-        ..Default::default()
-    })?;
+    let config = Config::load_with_cli_overrides(
+        config_overrides
+            .parse_overrides()
+            .map_err(anyhow::Error::msg)?,
+        ConfigOverrides {
+            sandbox_policy: Some(sandbox_policy),
+            codex_linux_sandbox_exe,
+            ..Default::default()
+        },
+    )?;
     let stdio_policy = StdioPolicy::Inherit;
     let env = create_env(&config.shell_environment_policy);
 

codex-rs/cli/src/lib.rs

@@ -3,6 +3,7 @@ mod exit_status;
 pub mod proto;
 
 use clap::Parser;
+use codex_common::CliConfigOverrides;
 use codex_common::SandboxPermissionOption;
 
 #[derive(Debug, Parser)]
@@ -14,6 +15,9 @@ pub struct SeatbeltCommand {
     #[clap(flatten)]
     pub sandbox: SandboxPermissionOption,
 
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+
     /// Full command args to run under seatbelt.
     #[arg(trailing_var_arg = true)]
     pub command: Vec<String>,
@@ -28,6 +32,9 @@ pub struct LandlockCommand {
     #[clap(flatten)]
     pub sandbox: SandboxPermissionOption,
 
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+
     /// Full command args to run under landlock.
     #[arg(trailing_var_arg = true)]
     pub command: Vec<String>,

codex-rs/cli/src/main.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 use codex_cli::LandlockCommand;
 use codex_cli::SeatbeltCommand;
 use codex_cli::proto;
+use codex_common::CliConfigOverrides;
 use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
 use std::path::PathBuf;
@@ -19,6 +20,9 @@ use crate::proto::ProtoCli;
     subcommand_negates_reqs = true
 )]
 struct MultitoolCli {
+    #[clap(flatten)]
+    pub config_overrides: CliConfigOverrides,
+
     #[clap(flatten)]
     interactive: TuiCli,
 
@@ -73,28 +77,34 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
 
     match cli.subcommand {
         None => {
-            codex_tui::run_main(cli.interactive, codex_linux_sandbox_exe)?;
+            let mut tui_cli = cli.interactive;
+            prepend_config_flags(&mut tui_cli.config_overrides, cli.config_overrides);
+            codex_tui::run_main(tui_cli, codex_linux_sandbox_exe)?;
         }
-        Some(Subcommand::Exec(exec_cli)) => {
+        Some(Subcommand::Exec(mut exec_cli)) => {
+            prepend_config_flags(&mut exec_cli.config_overrides, cli.config_overrides);
             codex_exec::run_main(exec_cli, codex_linux_sandbox_exe).await?;
         }
         Some(Subcommand::Mcp) => {
             codex_mcp_server::run_main(codex_linux_sandbox_exe).await?;
         }
-        Some(Subcommand::Proto(proto_cli)) => {
+        Some(Subcommand::Proto(mut proto_cli)) => {
+            prepend_config_flags(&mut proto_cli.config_overrides, cli.config_overrides);
             proto::run_main(proto_cli).await?;
         }
         Some(Subcommand::Debug(debug_args)) => match debug_args.cmd {
-            DebugCommand::Seatbelt(seatbelt_command) => {
+            DebugCommand::Seatbelt(mut seatbelt_cli) => {
+                prepend_config_flags(&mut seatbelt_cli.config_overrides, cli.config_overrides);
                 codex_cli::debug_sandbox::run_command_under_seatbelt(
-                    seatbelt_command,
+                    seatbelt_cli,
                     codex_linux_sandbox_exe,
                 )
                 .await?;
             }
-            DebugCommand::Landlock(landlock_command) => {
+            DebugCommand::Landlock(mut landlock_cli) => {
+                prepend_config_flags(&mut landlock_cli.config_overrides, cli.config_overrides);
                 codex_cli::debug_sandbox::run_command_under_landlock(
-                    landlock_command,
+                    landlock_cli,
                     codex_linux_sandbox_exe,
                 )
                 .await?;
@@ -104,3 +114,14 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
 
     Ok(())
 }
+
+/// Prepend root-level overrides so they have lower precedence than
+/// CLI-specific ones specified after the subcommand (if any).
+fn prepend_config_flags(
+    subcommand_config_overrides: &mut CliConfigOverrides,
+    cli_config_overrides: CliConfigOverrides,
+) {
+    subcommand_config_overrides
+        .raw_overrides
+        .splice(0..0, cli_config_overrides.raw_overrides);
+}

codex-rs/cli/src/proto.rs

@@ -2,6 +2,7 @@ use std::io::IsTerminal;
 use std::sync::Arc;
 
 use clap::Parser;
+use codex_common::CliConfigOverrides;
 use codex_core::Codex;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
@@ -13,9 +14,12 @@ use tracing::error;
 use tracing::info;
 
 #[derive(Debug, Parser)]
-pub struct ProtoCli {}
+pub struct ProtoCli {
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+}
 
-pub async fn run_main(_opts: ProtoCli) -> anyhow::Result<()> {
+pub async fn run_main(opts: ProtoCli) -> anyhow::Result<()> {
     if std::io::stdin().is_terminal() {
         anyhow::bail!("Protocol mode expects stdin to be a pipe, not a terminal");
     }
@@ -24,7 +28,12 @@ pub async fn run_main(_opts: ProtoCli) -> anyhow::Result<()> {
         .with_writer(std::io::stderr)
         .init();
 
-    let config = Config::load_with_overrides(ConfigOverrides::default())?;
+    let ProtoCli { config_overrides } = opts;
+    let overrides_vec = config_overrides
+        .parse_overrides()
+        .map_err(anyhow::Error::msg)?;
+
+    let config = Config::load_with_cli_overrides(overrides_vec, ConfigOverrides::default())?;
     let ctrl_c = notify_on_sigint();
     let (codex, _init_id) = Codex::spawn(config, ctrl_c.clone()).await?;
     let codex = Arc::new(codex);