codex-security scan --help renders 38 options as a flat 63-line list. Scope, mode/deep, model/provider, output/policy, workflow, and diagnostic flags are interleaved, and the ~57-character left column pushes descriptions far right. The count grew from 31 while adding project configuration in #742, and -c helps only after you already know which flags exist to put in the file.
Two findings from investigating this, recorded so the next person does not repeat them.
incur has no option-grouping API. formatCommand.Options (incur/dist/Help.d.ts) exposes alias, aliases, args, configFlag, commands, description, env, envSource, globals, examples, hint, hideGlobalOptions, options, and root. There is no section or group field. hint is plain text placed after examples and before global options, so it can hold a legend but cannot interleave headers. incur is third-party (wevm/incur), so real headers mean either an upstream feature request or a custom formatter in this repo.
Declaration order is render order. incur/dist/Help.js iterates Object.entries(schema.shape), so reordering the options object in cli.ts reorders help output with no library change.
That makes a cheap partial fix available: cluster the scan options by purpose in their declaration order. It improves adjacency but cannot add headers, which is arguably most of what makes a 38-option list readable — worth weighing before spending the churn on a file that #742 already touched heavily.
Reordering is safe with the current tests: the --schema assertions use toMatchObject and the 18 --help assertions use toContain, both order-insensitive.
Options, roughly in increasing cost:
- Reorder declarations into clusters. Cheap, no headers.
- Custom help formatter in this repo. Full control, duplicates
incur's rendering and has to track it.
- Upstream grouping support in
wevm/incur. Cleanest result, external turnaround.
codex-security scan --helprenders 38 options as a flat 63-line list. Scope, mode/deep, model/provider, output/policy, workflow, and diagnostic flags are interleaved, and the ~57-character left column pushes descriptions far right. The count grew from 31 while adding project configuration in #742, and-chelps only after you already know which flags exist to put in the file.Two findings from investigating this, recorded so the next person does not repeat them.
incurhas no option-grouping API.formatCommand.Options(incur/dist/Help.d.ts) exposesalias,aliases,args,configFlag,commands,description,env,envSource,globals,examples,hint,hideGlobalOptions,options, androot. There is no section or group field.hintis plain text placed after examples and before global options, so it can hold a legend but cannot interleave headers.incuris third-party (wevm/incur), so real headers mean either an upstream feature request or a custom formatter in this repo.Declaration order is render order.
incur/dist/Help.jsiteratesObject.entries(schema.shape), so reordering the options object incli.tsreorders help output with no library change.That makes a cheap partial fix available: cluster the
scanoptions by purpose in their declaration order. It improves adjacency but cannot add headers, which is arguably most of what makes a 38-option list readable — worth weighing before spending the churn on a file that #742 already touched heavily.Reordering is safe with the current tests: the
--schemaassertions usetoMatchObjectand the 18--helpassertions usetoContain, both order-insensitive.Options, roughly in increasing cost:
incur's rendering and has to track it.wevm/incur. Cleanest result, external turnaround.