Skip to content

Document extends Command#74

Closed
boblail wants to merge 1 commit intospectreconsole:mainfrom
boblail:lail/document-extends-command
Closed

Document extends Command#74
boblail wants to merge 1 commit intospectreconsole:mainfrom
boblail:lail/document-extends-command

Conversation

@boblail
Copy link

@boblail boblail commented Jan 20, 2026

Document and Command share 7 fields: arguments, options, commands, exitCodes, examples, interactive, and metadata.

The title and description fields of CliInfo serve the same purpose as the name and description fields of Command.

Document models the root command. Most CLIs model the root command the same way as subcommands — or with a subclass of the object used for subcommands. For example,

  • alecthomas/kong (Go): the root CLI and commands are all modeled as Go structs using Kong's grammar
  • oclif/oclif (TS): the root CLI and commands are all modeled as classes that extend Command
  • spf13/cobra (Go): the root command and subcommands are all instances of *cobra.Command
  • clap-rs/clap (Rust): the root and subcommands are all clap::Command values composed into a tree
  • remkop/picocli (Java): the root command and subcommands are all @Command-annotated classes/objects
  • commander-js/commander.js (JS): the “program” and its subcommands are all Command objects
  • CLIUtils/CLI11 (C++): the root app and subcommands are all CLI::App objects (subcommands are Apps too!)
  • dotnet/command-line-api (C#): the root command, System.CommandLine.RootCommand, extends System.CommandLine.Command
  • pallets/click (Python): the root command, click.Group, extends click.Command

This change:

  1. feat: adds summary to Command
  2. BREAKING: renames CliInfo#title to CliInfo#name
  3. BREAKING: hoists name, summary, and description up from CliInfo to Document
  4. refactor: extends Document from Command

resolves #70

`Document` and `Command` share 7 fields: `arguments`, `options`, `commands`, `exitCodes`, `examples`, `interactive`, and `metadata`.

The `title` and `description` fields of `CliInfo` serve the same purpose as the `name` and `description` fields of `Command`.

`Document` models the root command. Most CLIs model the root command the same way as subcommands — or with a subclass of the object used for subcommands.
For example,
- [alecthomas/kong](https://github.com/alecthomas/kong) (Go): the root CLI and commands are all modeled as Go structs using Kong's grammar
- [oclif/oclif](https://github.com/oclif/oclif) (TS): the root CLI and commands are all modeled as classes that extend `Command`
- [spf13/cobra](https://github.com/spf13/cobra) (Go): the root command and subcommands are all instances of `*cobra.Command`
- [clap-rs/clap](https://github.com/clap-rs/clap) (Rust): the root and subcommands are all `clap::Command` values composed into a tree
- [remkop/picocli](https://github.com/remkop/picocli) (Java): the root command and subcommands are all `@Command`-annotated classes/objects
- [commander-js/commander.js](https://github.com/commander-js/commander.js) (JS): the “program” and its subcommands are all `Command` objects
- [CLIUtils/CLI11](https://github.com/CLIUtils/CLI11) (C++): the root app and subcommands are all `CLI::App` objects (subcommands are Apps too!)
- [dotnet/command-line-api](https://github.com/dotnet/command-line-api) (C#): the root command, `System.CommandLine.RootCommand`, extends `System.CommandLine.Command`
- [pallets/click](https://github.com/pallets/click) (Python): the root command, `click.Group`, extends `click.Command`

This change
1. feat: adds `summary` to `Command`
2. BREAKING: renames `CliInfo#title` to `CliInfo#name`
3. BREAKING: hoists `name`, `summary`, and `description` up from `CliInfo` to `Document`
4. refactor: extends `Document` from `Command`
@boblail boblail force-pushed the lail/document-extends-command branch from 4f45d58 to 5a8586e Compare January 20, 2026 18:27
@patriksvensson
Copy link
Contributor

@boblail Thanks for engaging.

Pull requests, however, require an open issue. An issue is opened when a discussion reaches a consensus. I will therefore close this PR. I hope you understand.

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.

2 participants