feat(help): list commands by name in one aligned column

[jdx]

What

mise -h was the motivating case: 60 command rows, each carrying its full usage syntax inline, descriptions two spaces after whatever that syntax happened to be, so nothing lined up.

  bin-paths [--bin-names] [-J --json] [TOOL@VERSION]…  List all the active runtime bin paths
  bootstrap [FLAGS] <SUBCOMMAND> [aliases: bs]  Set up a machine for the current config in one command
  cache <SUBCOMMAND>  Manage the mise cache

--help was worse — it inlined every child's complete long_help, so the root page ran to hundreds of lines and bootstrap alone contributed a 40-line numbered list of its steps.

Both pages now read:

Commands:
  bin-paths     List all the active runtime bin paths
  bootstrap     Set up a machine for the current config in one command [aliases: bs]
  cache         Manage the mise cache
  en            Starts a new shell with the mise environment built from the
                current configuration

mise's root --help goes from hundreds of lines to 136.

Decisions

• One column per page, shared across help_heading groups, so a CLI that groups its commands reads as one table with rules through it — the rule the flag list already follows.
• Same summary on both pages: help, or the first line of help_long when a command wrote only that. A parent's list says what each child is for; what a child does at length belongs on the child's own page rather than repeated in every ancestor's.
• Aliases and deprecation trail the summary, so they wrap with the text instead of pushing every description out of the column.
• Rows show the leaf name, not the path that reached them: mise plugins -h lists install where it listed plugins install. This is what clap does.
• Sorting is untouched (display order, then rendered usage). The usage line is now only a sort key. Keeping it means this diff is a format change and not also a reordering of 211 pages.

Two things this change settles that were previously pinned as known-wrong:

• The deprecation label now trails the description in every renderer. They disagreed before — the Tera template wrote it before the description, usage-argv after — and the gates only passed because mise has no visible deprecated subcommand.
• The synthetic help row sits in the column with everything else instead of flush. corpus/render/03-sections.json had pinned the old behaviour explicitly "so that fixing it is a decision rather than an accident" — this is the decision.

Scope

All three renderers move together, as the gates require: usage-lib's Tera templates, usage-argv's hand-rolled pages, and the Go port. usage-argv's and Go's two command sections each converge on one function, since the pages are now identical.

Rendered help changes for every downstream CLI, so adopters with snapshot tests over their help output will see diffs. No API change.

Verification

• benches/gate/tests/help.rs — all 211 mise commands, -h and --help, byte for byte against the reference: green.
• benches/gate/tests/fleet.rs — the seven jdx CLIs plus the external shadows: green.
• go test ./... including go/conformance, which renders the Rust reference via xtask help-pages and compares: green.
• render-oracle reports zero divergences; two corpus vectors regenerated from it.
• mise run ci green; mise run render produces no drift, confirming markdown, manpage, and completion output are untouched.

Unrelated finding

While running the suite, the no_unexplained_disagreement proptest in benches/gate/tests/differential.rs found a real parse disagreement on mise github token --log-level=v --include-global --trace — usage-argv accepts it, usage-lib refuses, clap reports InvalidChoice. It reproduces on a clean checkout of 109821da, so it predates this work; I did not commit the regression seed it wrote, and it is not addressed here.

This PR description was generated by Claude Code.

---

Note

Medium Risk
User-visible help text changes for every downstream CLI (snapshots will break). Layout and wrapping logic is shared across three renderers, so a mismatch would be a visible regression, but there is no API or parse-path change.

Overview
Command lists on -h and --help now match: one aligned column of leaf names, then a short summary. Usage syntax and a child's full long_help stay on that child's own page instead of being inlined (or repeated) in every ancestor.

Aliases and deprecation trail the summary so they wrap with the text. The synthetic help row sits in the same column. Sorting is unchanged (display order, then rendered usage as a sort key only).

All three renderers move together: usage-lib templates, usage-argv (short and long share commands_section), and the Go port. Wrapping skips the common already-fits case and is no longer quadratic. Adopters with help snapshots will see diffs; markdown/man/completions are untouched.

^{Reviewed by Cursor Bugbot for commit 66f4c13. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Improvements

  • Help pages now display commands in aligned, width-aware rows with concise summaries.
  • Visible aliases and deprecation notices appear consistently alongside command descriptions.
  • Built-in help commands are shown when available.
  • Command listings no longer include usage arguments, reducing clutter.
  • Short and long help use consistent summaries, while detailed child-command help remains on the child’s own page.

• Documentation

  • Updated help guidance and examples to reflect the streamlined command-list format.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: b3c3073d-5b86-4611-9e46-74d71cda0b64

📥 Commits

Reviewing files that changed from the base of the PR and between 78d0d1b and ac236ab.

📒 Files selected for processing (1)

• argv/src/help.rs

Included review availability: Your plan provides up to 4 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Command listings now use aligned command-name columns with summaries, aliases, deprecation labels, and the built-in help entry. Short and long help share width-aware rendering. Library templates, tests, snapshots, and documentation reflect the new output.

Changes

Command help rendering

Layer / File(s)	Summary
Rust argv command rows argv/src/help.rs	Short and long help now share width-aware command rendering. Rows show command names, summaries, aliases, deprecation labels, and the built-in help command.
Go argv command rows go/argv/page.go, go/argv/page_long.go, go/argv/page_test.go	Go help uses aligned command-name columns and shared row formatting. The separate long-list renderer was removed.
Library help layout and templates lib/src/docs/models.rs, lib/src/docs/cli/mod.rs, lib/src/docs/cli/templates/*	Help models store row metadata. Rendering computes wrapped command rows and templates support inline and next-line layouts.
Help output validation and documentation conformance/tests/*, corpus/render/*, docs/*, lib/tests/parse.rs, usage-dynamic/tests/catalog.rs, usage-rs/tests/facade.rs	Tests, snapshots, and documentation now expect aligned single-line command rows and context-relative nested command names.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to ac236

This changes command-list formatting and summaries in generated help output, with expected snapshot diffs but no reported runtime or API behavior impact. No actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant HelpRenderer
  participant HelpModel
  participant HelpTemplate
  CLI->>HelpRenderer: request short or long help
  HelpRenderer->>HelpModel: build aligned command rows
  HelpRenderer->>HelpTemplate: pass rendered rows and help row
  HelpTemplate-->>CLI: render command listings

Loading

Poem

I hop through rows, aligned and bright,
Names meet summaries just right.
Aliases trail, old commands warn,
Help now greets each page at morn.
Wrapped lines rest without extra space.
— A rabbit, pleased with the new layout.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: listing commands by name in one aligned column.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch claude/mise-cli-help-review-544dac

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1ac8113. Configure here.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▃█▇▇▇▇▇▇▇▇▇▇	338,998,693 → 338,930,872	-0.02%	31.00 → 31.08ms	+0.24%
startup	▃▃▂▃▃▂▁▁▁▁▁▂▃█	876,883 → 885,383	+0.97%	0.93 → 0.97ms	+4.79%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	stripped binary, bytes
usage	1320432
bpaf	2493280
clap	3101832

framework	instructions, cold parse	vs usage
usage	8336	—
clap	6315224	757x
bpaf	21909147	2628x

                                              min       p01       p10    median
usage-rs: argv -> struct                      432       439       445       453  ns
clap: build tree + parse -> struct         529443    531695    534627    544530  ns
bpaf: build parser + parse -> struct      1635106   1635106   1641870   1658782  ns

usage: argv -> struct                             432 ns      0.43 µs
clap: build tree + parse -> struct             548567 ns    548.57 µs
clap: parse -> struct, tree reused              24469 ns     24.47 µs
clap: build tree only                          334128 ns    334.13 µs

_{66f4c13827cf vs 5f00afda6a61 · measured on the runner, not pushed to the history.}

[jdx]

The perf gate was right: usage --help rose 6.91% (873,420 → 933,781 instructions), because usage parses its own command line with usage-argv, so that benchmark is largely this code rendering a help page. Pushed ac236ab2, which brings it to +0.85% — under the gate — by fixing what the new command list was doing per row rather than by touching the gate.

Measured locally with cachegrind, the same command bench.startup runs:

	instructions	vs base
109821da (base)	859,600	—
this branch before the fix	917,311	+6.7%
incremental wrap width	903,731	+5.1%
fits fast path	883,151	+2.7%
byte-wise fits	872,481	+1.5%
assembled row	866,873	+0.85%

Four changes, in descending order of what they bought:

• wrap was quadratic. It recounted the whole line under construction for every word it appended. Carrying the width along costs nothing. This was already wrong before this branch — it just went unnoticed while only the long page wrapped.
• Text that already fits needs no wrapping, and most descriptions fit. fits answers that in one pass. It is allowed to be conservative, since a false answer only costs the wrap it was avoiding and wrap returns the same single line anyway — which is what lets it judge width in bytes (never fewer than characters) and hand anything non-ASCII to wrap rather than reasoning about which whitespace folds.
• The fast-path row is assembled rather than formatted. {usage:<col$} drags in the whole formatting machinery to pad a string, and that row is the line every entry on every page takes.
• command_row borrows the summary instead of building a string, since a summary and nothing else is what almost every row is.

Worth noting the first one is a net win beyond this branch: every wrapped page on both renderers is now cheaper than it was before. Byte-for-byte parity across mise's 211 pages, the fleet, and the Go conformance suite is unchanged — the two allocation fixes are provably output-identical and the gates confirm it.

This comment was generated by Claude Code.