CLI: improve command discoverability in --help and shell completion#1245
Merged
Conversation
🦋 Changeset detectedLatest commit: c230bf1 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
commit: |
talagluck
marked this pull request as draft
July 16, 2026 09:48
Shell completion was generated purely from the spec-derived command tree, so the hand-written groups' subcommands never tab-completed. Add a static HAND_WRITTEN_COMPLETIONS map (integration -> new/dev/publish/unpublish/tail/check, openapi -> publish) merged into the completion map before the scripts are emitted.
…D-12047, RND-12053) - Append a "Command groups (nested)" section to every group's --help so nested subgroups (e.g. organizations sites) are discoverable without drilling in. Root uses a compact one-line-per-group layout; subgroup pages use an indented tree. Attached generically by walking the Commander tree at runtime. - Sort subcommands alphabetically (built-in list via configureHelp + the tree). - Point `gitbook integrations --help` at the singular `gitbook integration` group for the build/publish lifecycle (new/dev/publish/...).
talagluck
force-pushed
the
cli-help-discoverability
branch
from
July 16, 2026 10:38
5530b69 to
024f776
Compare
talagluck
marked this pull request as ready for review
July 16, 2026 10:42
spastorelli
approved these changes
Jul 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cluster of three CLI discoverability follow-ups from #1205.
Changes
Nested command tree in
--help(RND-12047)Commander only lists a command's immediate children, so nested subgroups (
organizations sites,spaces content pages, …) were invisible until you drilled in one level at a time. A newhelp-tree.tswalks the Commander tree at runtime and appends a "Command groups (nested)" section to every group's help — root, generated subgroups, and hand-written groups alike, so it stays in sync automatically.Depth is capped at 1 level of nesting (subgroups only, no leaf verbs): it reveals e.g.
sitesunderorganizationsfrom the top level while keepinggitbook --helpbounded. Depth 2 was tried but explodes to 150+ lines on wide subtrees likesites(~30 nested collections) — the singleTREE_DEPTHconstant makes it trivial to revisit.Hand-written commands in shell completion (RND-12064)
Completion was generated purely from the spec-derived tree, so hand-written groups' subcommands never tab-completed. Added a small static
HAND_WRITTEN_COMPLETIONSmap ingenerate-commands.ts(integration→ new/dev/publish/unpublish/tail/check,openapi→ publish) merged into the completion map. Kept next to a note to stay in sync withapi-commands.ts.integrations→integrationpointer (RND-12053)People look under the plural
integrations(raw API ops) for the build/publish lifecycle, which actually lives under the singularintegration.gitbook integrations --helpnow points across.Test plan
tsc --noEmitcleanbun test— 40 passgitbook --help,gitbook organizations --help,gitbook integrations --help, and regenerated completion output