Group top-level CLI commands by user intent#812
Conversation
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
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (6)
Disabled knowledge base sources:
📝 WalkthroughWalkthroughThis 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 |
- 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)


A prospect flagged that
miren --helpwas 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 releaseand thedebugoutliers).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, andmiren helpto all go through the same path). The data side landed in the companion mirendev/mflags#14, where we added aCommandGroupProviderinterface, aGroupfield onChildEntryandCommandDoc, and exportedGetDirectChildrenso 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 bothmiren help <cmd>andmiren <cmd> --help, and thehelp aliasstandalone doc page was retired (aliases content already lives indocs/docs/app-toml.md#aliases). ATestAllTopLevelCommandsHaveKnownGrouptest catches new top-level commands that forget to declare a group, so the grouping stays complete as the CLI grows.Closes MIR-845