Make command help complete and consistent

[saioai]

Command help currently shows a short page and requires help --all for the full reference. This gives every help entrypoint the same complete command page. The layout follows gcloud's full reference, with concrete syntax and clearer flag descriptions.

What changes

• -h, --help, and help show the same page, including after valid options and through nested command paths.
• Short summaries lead into syntax, descriptions, examples, and complete local option definitions.
• Meaningful labels, separate defaults and environment names, and plain terminal prose make flags easier to scan.
• Child pages list inherited flags and link to the full root reference. Local image commands explain their output restrictions.
• Legacy help --all prints migration guidance before the same page. Command-owned images models --all stays available.
• Parser errors explain expected types, suggest known flag names, and print the relevant help command without exposing rejected values.

Commands

No new commands or flags. These help forms now show identical content:

openai images generate -h
openai images generate --help
openai help images generate

openai images generate --size 1024x1024 --help  # help after options
openai --help images generate                   # help before the command
openai models retrieve --help                   # positional, flag, and stdin forms
openai --help                                   # complete global option details

Help remains offline. Required-input notes preserve existing positional, flag, JSON, and YAML input contracts. Request defaults and output modes are unchanged.

Code

internal/clihelp owns help routing, synopses, flag references, and terminal prose. pkg/custom supplies presentation metadata and parser-error guidance. Generated path-input metadata follows existing command clones without changing flags or actions.

The completion change preserves manually typed legacy help flags while hiding them from suggestions. Generated API sources, dependencies, and main.go are unchanged.

Tested

Merged pinned main d32b3ae into the reviewed Help branch. The merge preserves c9817b1 and imports the exact upstream voice contract.

Fresh macOS validation at fc944da passed 1,166 public test/subtest checks, including required native Bash/zsh execution. Internal help/request-flag checks passed 540 records. Custom integration passed 191 records; voice contracts passed 29. These runs had no failures or skips.

The owned voice-type read cancellation test passed under the race detector. All package tests compiled. The candidate build, go vet ./..., and go mod verify passed.

Independent adversarial review passed 584 assertions across 527 processes. It covered complete-help equality, native copied commands, parser privacy, multipart inputs, and the merged voice contract.

Generated sources, schemas, and generation metadata match pinned main exactly. Main's trusted custom-code checker passed at 21/1,000 lines.

CI and native help checks passed at fc944da; conditional jobs were skipped.

The naming-only follow-up preserves every test assertion. It passed 11 focused test records, and the existing help CI selector discovers all four renamed tests. CI is rerunning at 1f6c0a8. The broader manual platform campaign remains deferred.

Demo

Real binaries on macOS, recorded at 90 and 56 columns. Before is main da762ff; after is this PR. Captures made no API requests. Images show labeled excerpts; the recorder also retains complete stdout. Fresh comparison checks confirm all four recorded help pages remain byte-identical after the pinned-main merge.

Before:

After:

Recording recipe

[github-actions]

Castiron custom code

Evaluated main: babc0e001e2def850d66303c08330ee704e6886c.

✅ No new custom-code files detected.

2 mixed files remain; 0 existing customizations changed.

Compared d32b3ae1d3fb → 1f6c0a8bb87e. Generated baselines verified.

2 existing customizations unchanged

• pkg/cmd/adminorganizationcertificate.go
• pkg/cmd/audiovoice.go

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 37814988099 --repo openai/openai-cli \
  --name castiron-custom-code-37814988099-1 --dir /tmp/castiron-custom-code-37814988099-1
git apply --stat /tmp/castiron-custom-code-37814988099-1/custom-code.patch
cat /tmp/castiron-custom-code-37814988099-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin babc0e001e2def850d66303c08330ee704e6886c 1f6c0a8bb87eff90526b39b27152aab411ac28ad
python3 scripts/castiron/custom_code_report.py report \
  --base babc0e001e2def850d66303c08330ee704e6886c \
  --head 1f6c0a8bb87eff90526b39b27152aab411ac28ad --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-1f6c0a8bb87e
cat /tmp/castiron-custom-code-1f6c0a8bb87e/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

[saioai]

@codex review

Please review commit fc944da950db66f8043caec22f2d7b0c53684561 against this PR's current base. Check public-command behavior, preserved input/output contracts, errors, and cancellation. Distinguish code defects from the documented validation limits.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T17:20:36.470036Z	1f6c0a8	Draft marked ready
🔒 Security Review	✅ Completed 2026-10-08T17:19:53.887616Z	1f6c0a8	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: fc944da950

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: fc944da950

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[markstuart-oai]

Reviewed 1f6c0a8bb87eff90526b39b27152aab411ac28ad. No actionable findings.

I checked help routing, legacy --all, flag and positional-input descriptions, terminal text, completion behavior, and parser-error guidance. The changes keep request handling separate from help presentation.

Source-only review; I did not run repository tests or builds. Hosted tests, build, lint, and help checks on macOS, Ubuntu, and Windows passed for this head.