Misleading `~/.codex/config.toml` references in CLI help text ignore $CODEX_HOME

Open 💬 1 comment Opened Apr 16, 2026 by taisukeoe

Summary

Several user-facing strings in the Codex CLI hardcode ~/.codex/config.toml even when $CODEX_HOME is set to a different directory. The runtime actually respects $CODEX_HOME correctly, but the misleading messages led me to believe my $CODEX_HOME override was being ignored.

Environment

  • Codex CLI: codex-cli 0.121.0 (installed via npm:@openai/codex)
  • OS: macOS (darwin, aarch64)
  • Shell: zsh
  • $CODEX_HOME set to a non-default directory via direnv

Repro

$ export CODEX_HOME=/tmp/my-codex-home
$ codex marketplace --help
...
Options:
  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          ...

The -c, --config help text says ~/.codex/config.toml even though the effective path is $CODEX_HOME/config.toml. The same hardcoded string appears across many subcommands (codex --help, codex debug --help, codex features --help, codex marketplace --help, etc.) because it is shared via the CliConfigOverrides help attribute.

Other hardcoded references observed

Running strings on the shipped binary (@openai/codex-darwin-arm64 0.121.0) shows at least these user-visible strings still referencing ~/.codex/ literally:

  1. -c, --config help (shared across subcommands):

> Override a configuration value that would otherwise be loaded from \~/.codex/config.toml\. ...

  1. A runtime hint/message:

> add a server launcher entry to \~/.codex/config.toml\ - \remove\ ...

  1. Documentation/example snippet shipped as help/skill text:

> Example \~/.codex/config.toml\ pattern:

The binary also contains correctly phrased strings such as $CODEX_HOME/config.toml and $CODEX_HOME/skills (or ~/.codex/skills when CODEX_HOME is unset), so the convention for handling a user-set CODEX_HOME already exists — the problematic lines just pre-date it.

Verified: runtime behavior is correct

I confirmed that codex marketplace add itself honors $CODEX_HOME:

$ CODEX_HOME=/tmp/codex-test codex marketplace add https://github.com/nonexistent/nonexistent
Error: git clone https://... failed with status exit status: 128
Cloning into '/tmp/codex-test/.tmp/marketplaces/.staging/marketplace-add-XXXX'...

Staging happens under $CODEX_HOME/.tmp/marketplaces/, not ~/.codex/.tmp/marketplaces/. So this is purely a messaging bug, not a functional one — but it is very confusing for anyone who sets $CODEX_HOME.

Suggested fix

Rewrite the offending strings to follow the convention already used elsewhere in the binary:

$CODEX_HOME/config.toml (or ~/.codex/config.toml when CODEX_HOME is unset)

Minimum fix candidates:

  • CliConfigOverrides help attribute for -c, --config
  • The mcp server-launcher hint/error
  • Any remaining static ~/.codex/config.toml example strings embedded in skill/help text

Happy to send a PR if desired.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗