codex --help formatting bug: --config Examples line breaks are not preserved

Open 💬 2 comments Opened Mar 2, 2026 by ftnext

What version of Codex CLI is running?

codex-cli 0.106.0

What subscription do you have?

ChatGPT Plus

Which model were you using?

N/A (help output issue; model selection not involved)

What platform is your computer?

Darwin 23.5.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

iTerm2 3.6.8

What issue are you seeing?

The --config help text in codex --help appears to have incorrect line wrapping in the Examples section.

Observed output:

Examples: - `-c model="o3"` - `-c
'sandbox_permissions=["disk-full-read-access"]'` - `-c
shell_environment_policy.inherit=all`

This makes the examples harder to read and can look malformed in narrow terminal widths.

What steps can reproduce the bug?

  1. Run:
codex --help
  1. Locate the -c, --config <key=value> section.
  2. Inspect the Examples block.
  3. In the affected build, examples are collapsed into one logical line and wrapped awkwardly.

What is the expected behavior?

The examples should preserve explicit line breaks, one example per line, e.g.:

Examples:
  - `-c model="o3"`
  - `-c 'sandbox_permissions=["disk-full-read-access"]'`
  - `-c shell_environment_policy.inherit=all`

Additional information

A local fix was validated by adding verbatim_doc_comment to the --config Clap arg in codex-rs/utils/cli/src/config_override.rs and confirming the built binary prints the expected multi-line examples.

diff --git a/codex-rs/utils/cli/src/config_override.rs b/codex-rs/utils/cli/src/config_override.rs
index 1592563a0..2f6fb20f5 100644
--- a/codex-rs/utils/cli/src/config_override.rs
+++ b/codex-rs/utils/cli/src/config_override.rs
@@ -32,6 +32,7 @@ pub struct CliConfigOverrides {
         value_name = "key=value",
         action = ArgAction::Append,
         global = true,
+        verbatim_doc_comment,
     )]
     pub raw_overrides: Vec<String>,
 }

View original on GitHub ↗

2 Comments

llljjjwww333 · 2 months ago

I prepared a small fix for this issue here:

https://github.com/llljjjwww333/codex/tree/fix/config-help-examples

Commit:
45f73bb15 Fix config override help examples formatting

What changed:

  • Moved the --config option details into explicit help / long_help strings so clap preserves the multi-line Examples section.
  • Added a regression test that renders long help and verifies the examples stay on separate lines instead of being collapsed into Examples: - ....

Validation:

  • git diff --check

I could not open a pull request because this repository currently limits PR creation to collaborators.

PabloMoralesEscandon · 1 month ago

I also tested a smaller variant that keeps the existing doc comments and adds \verbatim_doc_comment\ to the \--config\ arg instead of moving the
text into explicit \help\ / \long_help\ strings.

Branch:
https://github.com/PabloMoralesEscandon/codex/tree/fix/config-help-examples

Commit:
507ff6daa1 Preserve config override help examples formatting

Tested:

  • \cargo test -p codex-utils-cli\