feat(cli): add self-documenting commands with per-command help #1206
Conversation
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
- Add CommandMeta type for command metadata (name, short, usage, long, examples) - Each command file (run, tail, mcp, server) exports its own metadata - COMMANDS array in cli.ts pairs metadata with handlers - help.ts generates help dynamically from COMMANDS registry - Support 'spotlight help <cmd>' and 'spotlight <cmd> --help' for detailed help This prevents missing documentation by ensuring help text is colocated with command implementations.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
BYK
commented
Dec 13, 2025
- Add Command type combining meta and handler
- Each command exports default { meta, handler } object
- Simplify COMMANDS array to just [run, tail, mcp, server]
- Change changeset to minor (new feature)
Addresses PR review feedback.
BYK
commented
Dec 13, 2025
Member
Author
BYK
left a comment
BYK
left a comment
There was a problem hiding this comment.
Addressed both comments:
-
✅ Changed changeset from
patchtominor -
✅ Refactored to use standardized
{meta, handler}export pattern:- Added
Commandtype that combines meta and handler - Each command file now exports
default { meta, handler } satisfies Command COMMANDSarray simplified to[run, tail, mcp, server]CLI_CMD_MAPbuilt from this cleaner registry
- Added
Previously 'spotlight help run' would incorrectly trigger the special run command handling, setting cmdArgs to [] instead of ['run']. Now we check that 'run' is the first positional before applying the special handling, so 'spotlight help run' works correctly.
BYK
force-pushed
the
byk/feat/self-documenting-cli-commands
branch
from
bcd8fe7 to
bf31248
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| console.error(`Unknown command: ${targetCmd}`); | ||
| console.error(`Run 'spotlight help' to see available commands.`); | ||
| process.exit(1); | ||
| } |
There was a problem hiding this comment.
Bug: Help command shows error for valid "help" subcommand
When a user runs spotlight help help, the CLI prints "Unknown command: help" and exits with error code 1, even though "help" is listed as a valid command in the main help output (line 42). This happens because showCommandHelp searches only the COMMANDS array which contains [run, tail, mcp, server] but not the help command itself. The "help" command is hardcoded in the help text but excluded from the dynamic command registry, creating an inconsistency where users can't get detailed help about the help command.
Additional Locations (1)
BYK
pushed a commit
that referenced
this pull request
Dec 23, 2025
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and publish to npm yourself or [setup this action to publish automatically](https://github.com/changesets/action#with-publishing). If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @spotlightjs/[email protected] ### Minor Changes - Add support for continuous profiling (Profiling V2) ([#1202](#1202)) - Add self-documenting CLI commands with per-command help support ([#1206](#1206)) Each CLI command now provides its own metadata (short description, usage, detailed help, and examples). The main help output is generated dynamically from this metadata, and users can get detailed help for specific commands via `spotlight help <command>` or `spotlight <command> --help`. ### Patch Changes - Remove dead code ([#1214](#1214)) - Fix profile visualization issues in trace views: ([#1203](#1203)) - Update frame colors to use vibrant, high-contrast colors for better visibility - Add custom nanovis palette for Spotlight's dark theme - Fix sunburst center text showing bytes instead of sample counts - Fix treemap visibility with proper color contrast - added support for AI SDK v2 in AI Mode ([#1216](#1216)) - updated the empty pages of traces and envelopes ([#1213](#1213)) - open external links in default browser ([#1212](#1212)) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
Add self-documenting CLI commands so each command provides its own help metadata. The main help output is generated dynamically from all registered commands, preventing missing documentation.
Changes
CommandMetatype for command metadata (name, short, usage, long, examples)metaobjectCOMMANDSarray in cli.ts pairs metadata with handlershelp.tsgenerates help dynamically from the COMMANDS registryspotlight help <cmd>andspotlight <cmd> --helpfor detailed helpBehavior
spotlight --helpspotlight helpspotlight help runruncommandspotlight run --helpruncommandBenefits
meta, making help text a natural part of development