Skip to content

Group top-level CLI commands by user intent#812

Merged
phinze merged 3 commits into
mainfrom
phinze/mir-845-cli-de-emphasize-server-commands-for-deployer-context
May 18, 2026
Merged

Group top-level CLI commands by user intent#812
phinze merged 3 commits into
mainfrom
phinze/mir-845-cli-de-emphasize-server-commands-for-deployer-context

Conversation

@phinze
Copy link
Copy Markdown
Contributor

@phinze phinze commented May 18, 2026

A prospect flagged that miren --help was hard to navigate as a deployer. The top-level was a flat list of 30+ commands with server-administration sitting right next to deploy and rollback. For someone who only ever deploys an app, that's a lot of noise.

First instinct was to dim operator commands so they faded into the background, but that felt user-hostile, and it didn't solve the navigation problem so much as paper over it. Pivoted to positive grouping: five named buckets organized by what the user is trying to do (Getting started, Monitoring your app, Configuring your app, Client operations, Server operations). Group headers render in bold yellow (matching our table-header convention) with the existing faint sub-command counts. The exercise was itself useful in noticing where the CLI surface had drifted (a couple of follow-ups noted but not landed here, like download release and the debug outliers).

The rendering side moved into the runtime layer. mflags' role is to parse arguments and own the command tree; this PR makes the runtime render its own top-level help (and intercepts miren, miren -h, and miren help to all go through the same path). The data side landed in the companion mirendev/mflags#14, where we added a CommandGroupProvider interface, a Group field on ChildEntry and CommandDoc, and exported GetDirectChildren so callers can walk the tree. Same boundary makes future help-rendering polish a runtime concern, not a mflags one.

Along the way: miren help <space-separated path> now works the same as the dotted form, the help footer mentions both miren help <cmd> and miren <cmd> --help, and the help alias standalone doc page was retired (aliases content already lives in docs/docs/app-toml.md#aliases). A TestAllTopLevelCommandsHaveKnownGroup test catches new top-level commands that forget to declare a group, so the grouping stays complete as the CLI grows.

Closes MIR-845

Prospect feedback flagged that miren's top-level help dumped a flat
list of 30+ commands, with server-administration commands sitting
right next to deploy and rollback. For someone who only ever deploys
an app, that's a lot of noise to navigate around.

Reorganizes top-level help into five named groups (Getting started,
Monitoring your app, Configuring your app, Client operations, Server
operations) so deployers see what they need first and the operator
surface is still discoverable but visually separated. Headers render
in bold yellow via lipgloss; sub-command counts dim.

The rendering moved into the runtime layer. mflags now just exposes
group metadata via the new CommandGroupProvider interface (see the
companion PR mirendev/mflags#14), and the runtime walks the command
tree and styles output itself. Same model means future help-rendering
polish doesn't keep pulling presentation logic back into mflags.

A drift-prevention test catches new top-level commands that forget to
declare a group, so the grouping stays complete as the CLI grows.

Closes MIR-845
@phinze phinze requested a review from a team as a code owner May 18, 2026 22:29
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 18, 2026

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 205c25d5-81d3-47d4-afbd-b3abcf26444e

📥 Commits

Reviewing files that changed from the base of the PR and between 87dd5e4 and e39c952.

⛔ Files ignored due to path filters (1)
  • go.sum is excluded by !**/*.sum
📒 Files selected for processing (6)
  • docs/command-sidebar.json
  • docs/docs/command/alias.md
  • docs/docs/command/disk.md
  • docs/docs/command/help-alias.md
  • docs/docs/command/help.md
  • docs/docs/commands.md

Disabled knowledge base sources:

  • Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.


📝 Walkthrough

Walkthrough

This change introduces a help grouping system for the CLI. Help groups organize top-level commands into labeled categories for the top-level help output. The PR defines group constants, adds infrastructure to tag commands and sections with groups, implements grouped help rendering, wires it into the CLI entry point, tags all existing commands, improves help command parsing, and adds validation that all commands have assigned groups.


Comment @coderabbitai help to get the list of available commands and usage tips.

@phinze
Copy link
Copy Markdown
Contributor Author

phinze commented May 18, 2026

New help in action:

2026-05-18 at 17 32 51@2x

Copy link
Copy Markdown
Contributor

@evanphx evanphx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Image

my.. it's so... beautiful.

@phinze phinze enabled auto-merge May 18, 2026 22:44
@phinze phinze merged commit 2944e79 into main May 18, 2026
18 of 19 checks passed
@phinze phinze deleted the phinze/mir-845-cli-de-emphasize-server-commands-for-deployer-context branch May 18, 2026 22:53
maryelizbeth pushed a commit that referenced this pull request May 20, 2026
- Fix Pi link to point to pi.dev instead of nonexistent GitHub repo
- Replace placeholder paths with git clone workflow for Codex and OpenCode
- Add language specifier to Amp code block
- Simplify miren help examples (dots/quotes no longer needed per #812)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants