codex exec --help advertises a second positional [COMMAND] but parser rejects it

[aquiles-ai123]

codex exec --help advertises a second positional [COMMAND], but the parser rejects it

Summary

codex exec --help currently shows this usage line:

Usage: codex exec [OPTIONS] [PROMPT] [COMMAND]

That suggests exec accepts two positionals: a prompt and then a command.

In practice, providing a second positional fails immediately in argument parsing with:

error: unexpected argument 'false' found

So the help output and the actual parser behavior disagree.

Repro

Check the help text:

codex exec --help | sed -n '1,20p'

Observed excerpt:

Run Codex non-interactively

Usage: codex exec [OPTIONS] [PROMPT] [COMMAND]

Now try to use stdin for the prompt and pass false as the advertised second positional:

printf '' | codex exec --ephemeral --skip-git-repo-check --color never -C /home/cryptotrading74 - false
printf "outer_exit=%s\n" "$?"

Observed output:

error: unexpected argument 'false' found

Usage: codex exec [OPTIONS] [PROMPT] [COMMAND]

For more information, try '--help'.
outer_exit=2

Expected behavior

One of these should be true:

• codex exec should actually accept the advertised second positional [COMMAND]
• or the help text should stop advertising [COMMAND]

Actual behavior

The help text advertises [COMMAND], but the parser rejects any second positional as unexpected.

Why this matters

This is misleading for automation and scripting, because the CLI help describes an invocation form that cannot be used.

Additional information

This looks related in spirit to other exec --help mismatches such as #13614, but this report is specifically about the phantom [COMMAND] positional shown in usage.

[middleDuckAi]

Repro

• Reproduced this on current main.
• codex exec --help was advertising a phantom second positional [COMMAND] even though the parser only supports the real invocation forms.

Root Cause

• The mismatch was in the generated help contract, not in the parser behavior.
• I prepared a narrow fix that only aligns the help output with the parser and adds focused regression coverage.

Validation

• cargo fmt --all --check
• cargo run -p codex-cli -- exec --help | sed -n '1,20p'
• cargo test -p codex-cli exec_help_does_not_advertise_a_second_positional
• cargo test -p codex-cli exec_resume
• printf '' | cargo run -p codex-cli -- exec --ephemeral --skip-git-repo-check --color never - false

Docs / Help Impact

• Yes. This changes user-facing help output.

Risk

• Low. This is scoped to help text plus a regression test, with no parser semantic change.

Maintainer Pickup

gh pr create --repo openai/codex --base main --head middleDuckAi:middleDuck/codex-15535-exec-help-contract --title "$(gh pr view 1 --repo middleDuckAi/codex --json title --jq .title)" --body "$(gh pr view 1 --repo middleDuckAi/codex --json body --jq .body)"

[etraut-openai]

Thanks for the bug report. This will be addressed in the next release.