Commands
The Command interface, BaseCommand, NewBaseCommand, and the Verbosity helper.
A command is a struct that embeds BaseCommand[T] and implements Run. The embedding satisfies most of the Command interface for free.
Command
type Command[T any] interface {
// Name gets or sets the command name. Pass "" to get, non-empty to set.
Name(name string) string
// Add registers a subcommand under this command.
Add(name string, cmd Command[any])
// Options returns a pointer to the config struct for flag parsing.
Options() any
// Commands returns the list of registered subcommands.
Commands() []Command[any]
// Run executes the command logic with parsed global options and unknown args.
Run(options GlobalFlags, unknowns Unknowns) error
// Validate checks the parsed options map against struct validation rules.
Validate(options map[string]any) error
// Help returns a short one-line description shown in command listings.
Help() string
// Description returns a longer, multi-line description shown in detailed and agent help.
// Help stays the one-line listing summary; Description carries the richer body
// (paragraphs, install instructions, ...). Empty by default.
Description() string
// Examples returns usage examples shown in detailed and agent help.
// Each example is a slice of lines: the first is the invocation,
// any following lines are sample output shown beneath it. Nil by default.
Examples() [][]string
// Args returns multi-line descriptions for positional arguments, keyed by zero-based position.
// Augments the single-line `help:` tag. Nil by default.
Args() map[int][]string
// Flags returns multi-line descriptions for flags, keyed by the flag as written (e.g. "--query, -q").
// Augments the single-line `help:` tag. Nil by default.
Flags() map[string][]string
}The interface every command satisfies. T is the config struct whose fields define the flags and args. BaseCommand provides everything except Run, and default no-op implementations of the help providers (Description, Examples, Args, Flags) that you override to enrich help.
BaseCommand
type BaseCommand[T any] struct {
command string
commands []Command[any]
Inputs *T
}Embed it in your command struct to get name management, subcommand registration, config handling, and validation. The parsed and merged config lands in Inputs, a *T, before Run is called.
func NewBaseCommand[T any]() BaseCommand[T]Constructs a BaseCommand with an initialized subcommand slice. Use it when registering a command.
app.Add("serve", &ServeCommand{BaseCommand: cli.NewBaseCommand[ServeConfig]()})Verbosity
type Verbosity struct {
V1 bool `short:"v" help:"Verbose output (-v)"`
V2 bool `short:"vv" help:"More verbose output (-vv)"`
V3 bool `short:"vvv" help:"Most verbose output (-vvv)"`
}An optional embeddable flag group giving the conventional -v, -vv, and -vvv switches without the framework imposing any verbosity of its own. Embed it in a command's config to get the flags and the level query. The three flags are independent switches, so read the selected level rather than the bool fields.
func (v Verbosity) Level() int
func (v Verbosity) Verbose() bool
func (v Verbosity) AtLeast(level int) boolLevel returns 0 when no flag was passed, up to 3 for -vvv, with the highest flag winning. Verbose reports whether any verbosity flag was passed. AtLeast reports whether the selected level is at or above a threshold.