CLI: custom root-help renderer with real grouped sections

[saltyskip]

Replaces the previous PR's "Quick Reference + flat command list" with actual grouped sections in the Commands list itself. No duplication.

Before vs after

Before (PR #170 — Quick Reference block above, flat list below):

$ rift -h
Deep links for humans and agents

Usage: rift <COMMAND>

Commands:
  init         Create or verify your Rift account ...
  login        Connect this machine ...
  logout       Remove stored credentials ...
  ... (15 more commands, alphabetical-ish)

And a separate "Quick reference" block only on --help.

After:

$ rift
Deep links for humans and agents

Usage: rift <COMMAND>

Account:
  init         Create or verify your Rift account and connect this machine
  login        Connect this machine with an existing API key
  logout       Remove stored credentials from this machine
  whoami       Show the current account and verify the API key
  doctor       Check what capabilities are unlocked and what to do next

Resources:
  links        Manage deep links
  apps         Register and manage mobile apps
  domains      Add and verify custom domains
  team         Manage team members on your tenant
  analytics    Funnel stats and (future) timeseries across one or more links

Billing:
  subscribe    Start or upgrade a paid subscription (opens Stripe in browser)
  cancel       Cancel your subscription at current_period_end
  billing      Show plan tier, limits, and renewal date

Meta:
  version      Print the CLI version and build target
  update       Download and install the latest CLI release
  completions  Generate shell completions (omit shell to print install instructions for your shell)

Aliases: me=whoami, ver=version, signout=logout, ls=list, rm=remove, new=create

Options:
  -h, --help     Print help
  -V, --version  Print version

Run `rift <command> --help` for details on a specific command.

rift, rift -h, and rift --help all produce the same output. Subcommand help (rift links --help, rift team rm -h) is unchanged — clap handles those.

How it works

clap 4 doesn't natively group subcommands. The workaround:

• Each Command variant carries #[command(display_order = N)].
• N lives in a numeric range that maps to a group: 10–19 Account, 20–29 Resources, 30–39 Billing, 40–99 Meta.
• print_grouped_help() introspects Cli::command(), partitions subcommands by range, renders each group with a header.
• A small argv check before clap::parse() intercepts the root-help cases and calls print_grouped_help().

Maintenance cost: each new command picks an appropriate display_order from the right group's range. Forgetting? It falls into an "Other:" section, still visible.

Test plan

• cargo fmt --check, cargo clippy -D warnings, cargo test on client/cli
• rift (bare), rift -h, rift --help all render the grouped output
• rift links --help unchanged (clap default)
• rift links list -h unchanged (clap default, nested)
• rift -V / rift --version still works (clap handles before our intercept)
• Post-merge auto-patch publishes rift-cli-v0.2.4. After rift update, confirm rift shows grouped help.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rift	Ready	Preview, Comment	May 26, 2026 3:46pm