Make CLI help easier to scan

[robzolkos]

Make the top-level help faster to scan by putting frequent email workflows first, separating specialized commands into task-oriented groups, and adding references for cross-cutting CLI behavior. Existing commands, flags, output behavior, and the executable command catalog remain compatible.

Review readiness: ✅ Yes
Risk: 🟢 Low — this changes help presentation and adds non-runnable help topics without changing command execution.
Decision: None

✅ Change — common email commands lead and detailed references remain discoverable

Before

hey --help
├── INTERACTIVE
│   └── tui
└── EMAIL
    ├── 34 commands in one group
    ├── compose and reply below resource-management pairs
    └── long global flag descriptions

After

hey --help
├── CORE COMMANDS
│   └── tui → box → threads → reply → compose → search  ← CHANGED
├── task-oriented command groups
├── concise root flag summaries
└── HELP TOPICS
    ├── output
    ├── exit-codes
    ├── environment
    └── linked-accounts  ← CHANGED

Runnable commands that also own subcommands now show both valid usage forms. Help references bypass runtime configuration, account selection, network access, credential migration, and skill refresh; shell completion includes both commands and help topics after hey help.

✅ Evidence — automated checks and the complete rendered help flow pass

• ✅ GOWORK=off make check — unit tests, formatting, lint, surface compatibility, and repository checks passed.
• ✅ GOWORK=off make build — built ./bin/hey for local review.
• ✅ Focused tests pin the categorized output, 100-column limit, unique category membership, topic rendering/catalog exclusion, runtime-hook bypass, topic completion, and dual usage forms.
• ✅ Rendered help recording — shows the complete root help at this head, from frequency-ordered core commands through flags, examples, and discovery links.

Root help: 99 lines
Longest line: 88 columns (previously 119)

✅ Scope — help discovery changes; executable behavior remains compatible

Included: root command grouping and ordering, concise root-only flag descriptions, four Cobra additional-help topics, broader examples, dual usage lines for runnable parents, safe help execution, completion, tests, and README reference documentation.

Preserved: every existing command and flag, detailed inherited flag descriptions, hey commands output, .surface, output formats, authentication, account behavior, and TUI behavior.

Non-goal: renaming singular/plural command pairs or introducing a new noun-first command hierarchy.

➖ Delivery — no rollout, migration, configuration, or cleanup work

The change ships with the CLI binary. Rollback is a normal code revert; no data or external resources are involved.

✅ Review decision — no unresolved decision; focus on hierarchy and reference wording

Please confirm that the CORE COMMANDS order reflects the normal email workflow and that the four help topics describe the existing behavior at the right level of detail.

✅ Review path — start with the command hierarchy, then references and proof

1. internal/cmd/help.go — root hierarchy, concise flag summaries, completion, and rendering.
2. internal/cmd/help_topics.go — the four user-facing references.
3. internal/cmd/help_test.go — behavior and compatibility proof.
4. internal/cmd/root.go and README.md — registration, safe lifecycle, and documentation.

Origin and supporting links: Basecamp card

---

Summary by cubic

Makes root CLI help easier to scan by promoting frequent email workflows, grouping specialized commands, adding help topics with completion, and shortening global flag descriptions. Previously, help mixed interactive and 34 email commands with long flag text; now CORE COMMANDS lead, task groups follow, reference topics are discoverable, and command execution is unchanged.

Review

• Confirm CORE COMMANDS order reflects normal email flow and includes contacts, boxes, calendars, todo, and journal; ensure MAIL, WRITE & SHARE, SAVED CONTENT, ORGANIZE, and CALENDAR & TASKS stay small and have no duplicates.
• Check root flag summaries use concise text and that -h is shown for --help.
• Verify help topics (output, exit-codes, environment, linked-accounts) render as references, are excluded from hey commands, and appear in hey help completion alongside commands; exit-codes clarifies operational failure statuses.
• Ensure runnable parents show both usage forms and that help rendering bypasses runtime setup and skill refresh without affecting command runs.

Rollout

• No migration or configuration required; commands, flags, and outputs remain compatible.

^{Written for commit bfbb4a7. Summary will update on new commits.}

[Copilot]

Pull request overview

Reorganizes CLI help for faster scanning while preserving command behavior.

Changes:

• Groups commands by common workflows.
• Adds four cross-cutting help topics and completion.
• Expands documentation and automated help checks.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Documents help discovery and references.
internal/cmd/root.go	Registers topics and bypasses runtime hooks for help.
internal/cmd/help.go	Implements grouped rendering and completion.
internal/cmd/help_topics.go	Defines cross-cutting reference content.
internal/cmd/help_test.go	Tests rendering, discovery, lifecycle, and usage forms.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.