Global flags
The built-in globals every command receives, and the clean-exit sentinels.
Four flags are parsed before dispatch and passed to every command's Run as a cli.GlobalFlags value. They are handled by the framework, so a command reads them but never has to parse them.
The built-in flags
| Flag | Short | Purpose |
|---|---|---|
--help | -h | Show help for the matched command instead of running it. |
--version | -V | Print the app version and exit. |
--cwd | Override the working directory for the command. Long-only. | |
--help-format | Choose the help output format (plain, plain-flags, pretty, md, json, jsonschema). | |
--help-values | With --help, annotate each flag with its resolved value. Implies --help. |
The reserved shorts are kept minimal so they never squat on your own flags. Only -h and -V are taken, which leaves -v, -c, and --format free for your commands. -h and -V trigger regardless of position, even directly after a value-taking flag.
Reading globals in a command
Run receives the resolved globals as its first argument.
func (c *DeployCommand) Run(globals cli.GlobalFlags, _ cli.Unknowns) error {
if globals.Cwd != "" {
if err := os.Chdir(globals.Cwd); err != nil {
return fmt.Errorf("failed to change directory: %w", err)
}
}
// ...
return nil
}The clean-exit sentinels
When the framework handles --help or --version, it prints the output itself and then returns a sentinel error so the call site knows a clean exit was already handled. IsRealError filters them, returning false for nil, ErrShowingHelp, and ErrShowingVersion, and true for anything else.
if err := app.Run(os.Args[1:]); cli.IsRealError(err) {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
os.Exit(1)
}Note
Prefer cli.IsRealError(err) over enumerating the sentinels by hand. It keeps the call site correct even as the framework adds more clean-exit signals.
Optional verbosity
The framework imposes no verbosity flag of its own, so -v stays yours. Embed cli.Verbosity in a command's config to get the conventional -v, -vv, and -vvv switches, then read the level with Level, Verbose, or AtLeast.
type BuildConfig struct {
cli.Verbosity // -v / -vv / -vvv
Target string `arg:"target"`
}
func (c *BuildCommand) Run(_ cli.GlobalFlags, _ cli.Unknowns) error {
if c.Inputs.AtLeast(2) {
fmt.Println("verbose build")
}
return nil
}