Subcommands

Add registers a command and returns it, so command trees chain naturally. A command registered on the app is a top-level command, and a command registered on another command is its subcommand.

Building a tree

Call Add on the app for a top-level command, and on the returned command for its children.

db := app.Add("db", &DBCommand{BaseCommand: cli.NewBaseCommand[struct{}]()})
db.Add("migrate", &MigrateCommand{BaseCommand: cli.NewBaseCommand[struct{}]()})
db.Add("seed", &SeedCommand{BaseCommand: cli.NewBaseCommand[struct{}]()})
// runs the leaf:  tool db migrate

The framework matches the deepest command in the path, then parses the remaining args against that command's config struct.

Parent placeholders

A parent that only groups subcommands, such as db, often has no behavior of its own. Register help.NewParentPlaceholder() for it so invoking the parent directly lists its children instead of doing nothing.

import "github.com/toaweme/cli/commands/help"

db := help.NewParentPlaceholder()
app.Add("db", db)
db.Add("migrate", &MigrateCommand{BaseCommand: cli.NewBaseCommand[struct{}]()})
db.Add("seed", &SeedCommand{BaseCommand: cli.NewBaseCommand[struct{}]()})
// `tool db` lists migrate and seed, `tool db migrate` runs the leaf

Under the hood the placeholder's Run returns cli.ErrDisplaySubCommands. Any command can return that sentinel to get the same child listing, which is useful when a command wants to list its subcommands unless given a specific one.

func (c *DBCommand) Run(_ cli.GlobalFlags, _ cli.Unknowns) error {
	return cli.ErrDisplaySubCommands
}

A default command

Default sets the command that runs on a bare invocation with no arguments. With a default set, tool runs the default, and tool --flag behaves like tool <default> --flag.

app.Default(&StatusCommand{BaseCommand: cli.NewBaseCommand[StatusConfig]()})

Without a default, a bare invocation shows help. A leftover positional that names no command is reported as not found, with help for the closest command that did match.