Skip to content

feat: group root help into Setup, Resources, Advanced, and Maintenance - #34

Merged
imjohnbo merged 1 commit into
mainfrom
claude/commands-organization-513a08
Sep 9, 2026
Merged

feat: group root help into Setup, Resources, Advanced, and Maintenance#34
imjohnbo merged 1 commit into
mainfrom
claude/commands-organization-513a08

Conversation

@imjohnbo

@imjohnbo imjohnbo commented Sep 9, 2026

Copy link
Copy Markdown
Owner

What changed

kit --help listed 25 commands in one flat list. The 12 resource commands people use most sat between setup and maintenance commands. The root help now lists them under four headings:

Setup:        init, login, logout, account, config, setup-skill, completion
Resources:    broadcasts, custom-fields, email-templates, forms, posts,
              purchases, segments, sequences, snippets, subscribers, tags,
              webhooks
Advanced:     api, bulk
Maintenance:  doctor, upgrade, help

Setup follows the first-run flow. Resources stay alphabetical. The implicit help command joins Maintenance, so no command stands alone under a bare "Commands:" heading.

  • Commander 13 to 14. Version 14 adds native help groups (commandsGroup()), so the grouping is a few lines in src/program.js. Commander 14 keeps the Node 20 floor that engines already requires. Commander 15 requires Node 22.12, so this stops at 14.
  • Five descriptions trimmed so every root command fits on one line at 80 columns: setup-skill, completion, webhooks, api, and doctor. The dropped detail moves into each command's own --help. For example, kit api --help now shows the escape-hatch note and two examples, and kit completion --help shows the three shell rc lines.
  • README Commands section restructured into the same four groups, with the resource sections nested under Resources. Every existing line carries over. The api and doctor commands gain short sections, which they did not have before.

Why

Grouping helps a new user find the setup commands and a returning user skip past them. Trimming the descriptions keeps each group compact, because a wrapped line takes as much space as two commands.

For the reviewer

  • Presentation only. spec/cli-surface.json records names, arguments, and flags, not help text. The snapshot is unchanged, so the release gate sees no breaking change.
  • New test scripts/program-help-groups.test.js spawns the real binary and asserts the heading order, each group's members, alphabetical Resources, and no wrapped descriptions. Both suites failed before the change and pass after it.
  • Full suite: 796 pass, 0 fail, 1 pre-existing skip (the non-macOS Keychain test).
  • skills/kit/SKILL.md keeps its own "Auth & Config" grouping. It serves Claude rather than a terminal, so it is out of scope here.

Twenty-five commands in one flat list hid the twelve resource commands between setup and maintenance commands. The root help now lists them under four headings. Setup follows the first-run flow, Resources stay alphabetical, and the implicit help command joins Maintenance instead of standing alone under a bare Commands heading.

Bump Commander from 13 to 14 for native help groups. Commander 14 keeps the Node 20 floor.

Trim the five descriptions that wrapped at 80 columns (setup-skill, completion, webhooks, api, doctor). The dropped detail moves into each command's own --help.

Mirror the four groups in the README Commands section. Every existing line carries over. The api and doctor commands gain short sections.

Grouping is presentation only. The surface snapshot is unchanged.
@imjohnbo
imjohnbo merged commit ae5136b into main Sep 9, 2026
2 checks passed
@imjohnbo
imjohnbo deleted the claude/commands-organization-513a08 branch September 9, 2026 16:57
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.

1 participant