App

NewApp, the App interface and its chainable setters, Config, and the clean-exit sentinels.

The App owns the command set, the global flags, and an ordered chain of config resolvers, and dispatches os.Args to the matched command.

NewApp

func NewApp(config Config, opts GlobalFlags) App

Creates an app from config (the serializable identity) and the default values for the global flags. Attach resolvers and output formats with the chainable setters, register commands with Add, Default, and Help, then dispatch with Run.

app := cli.NewApp(cli.Config{Name: "srv", Version: "1.0.0"}, cli.GlobalFlags{})

App

type App interface {
	// Commands returns the registered top-level commands.
	Commands() []Command[any]
	// DefaultCommand returns the command registered via Default, or nil when none is set.
	DefaultCommand() Command[any]
	// Config returns the app identity (the serializable DTO).
	Config() Config
	// OutputFormats returns the registered help output codecs, in registration order.
	OutputFormats() []OutputCodec
	// Resolve appends config Resolvers to the chain used to populate each command's Options() before Run,
	// and returns the app for chaining. Resolvers run in the order registered (across all Resolve calls),
	// lowest precedence first, then env, then flags. With none registered, only env and flags apply.
	Resolve(resolvers ...Resolver) App
	// HelpOutputs registers additional help output codecs (e.g. the yaml/toml addons) and returns the app for chaining.
	// Each codec's name, derived from its Extension (".yml" -> "yml"), becomes a valid --help-format value
	// and is advertised in help.
	HelpOutputs(formats ...OutputCodec) App
	// Default sets the command run when no arguments are given; it returns cmd.
	Default(cmd Command[any]) Command[any]
	// Add registers cmd under name and returns it, so subcommands chain off the result.
	Add(name string, cmd Command[any]) Command[any]
	// Run parses osArgs and dispatches to the matched command.
	// Help and version requests surface as the ErrShowingHelp/ErrShowingVersion sentinels.
	Run(osArgs []string) error
	// Help registers cmd as the command that renders help, so callers never have to know the reserved name.
	// Use it instead of Add: app.Help(help.NewHelpCommand(...)).
	Help(cmd Command[any]) Command[any]
}

The setters return the app, so registration chains. Add registers a command under a name and returns it, so subcommands chain off the result. Default sets the command that runs on a bare invocation. Help registers the help renderer under the reserved name. Resolve and HelpOutputs append to the resolver chain and the output codecs. Run parses the args, merges and validates each command's config, then dispatches.

Config

type Config struct{}

The application identity, a light DTO of plain values that round-trips through json and yaml. Name is the binary name shown in help, and Version is printed by --version.

IsRealError

func IsRealError(err error) bool

Reports whether err is a genuine failure, as opposed to a clean-exit sentinel the framework returns once it has already printed help or the version. It returns false for nil and for ErrShowingHelp and ErrShowingVersion, so a caller need not enumerate the sentinels.

Sentinels

The framework returns these once it has handled a request itself, so the call site can treat them as clean exits.

var ErrShowingHelp = errors.New("showing help")
var ErrShowingVersion = errors.New("showing version")

ErrShowingHelp and ErrShowingVersion are what IsRealError filters. A command can also return ErrDisplaySubCommands to have its subcommand list printed.

var ErrDisplaySubCommands = errors.New("print sub commands")
var ErrCommandNotFound = errors.New("command not found")
var ErrNoCommands = errors.New("no commands registered")

Edit or read the source on GitHub