Global flags
GlobalFlags and Unknowns, the two values every Run receives.
Every command's Run receives the resolved global flags and the arguments that matched no field.
GlobalFlags
type GlobalFlags struct {
// Cwd overrides the working directory for the command.
// Long-only: "cwd" is too niche to justify squatting on -c, the most common short for a "config" flag.
Cwd string `arg:"cwd" env:"CWD" help:"Current working directory"`
// Help triggers help display instead of running the matched command.
// -h/--help is the one short the whole ecosystem reserves, so it keeps its short.
Help bool `arg:"help" short:"h" env:"HELP" help:"Show help"`
// HelpValues, with --help, annotates each flag with its resolved value
// (the merge of defaults, config, env, and flags for the invoked command).
// Values are prefix-masked so secrets sourced from env or a .env file are not
// exposed in full in help that gets pasted into logs, issues, or screenshots.
// Off by default; passing --help-values implies --help.
HelpValues bool `arg:"help-values" help:"With --help, show each flag's resolved value (prefix-masked)"`
// HelpFormat controls help output. It is --help-format, not --format:
// the bare name is the one apps most often want for their own command output (json/yaml/table/csv),
// and squatting on it also meant the framework rejected any unrecognized value app-wide before the command ran.
// The allowed values come from the oneof rule, which also drives the "(one of: ...)" hint shown in help.
HelpFormat string `arg:"help-format" help:"Help output format" rules:"oneof:plain,plain-flags,pretty,md,json,jsonschema"`
// Version prints the application version and exits.
// Short is capital -V (clap-style) so lowercase -v stays free for the author's own "verbose" flag,
// which is what users overwhelmingly expect -v to mean.
Version bool `arg:"version" short:"V" env:"VERSION" help:"Show version"`
}The built-in flags parsed before dispatch and passed to every Run. Cwd overrides the working directory. Help and Version trigger the built-in help and version output. HelpValues, with --help, annotates each flag with its resolved value. HelpFormat selects the help output format. The reserved shorts are only -h and -V, so -v, -c, and --format stay yours.
Unknowns
type Unknowns struct {
// Args are positional arguments not matched to numbered struct tags.
Args []string
// Options are key-value flags not defined in the command's config struct.
Options map[string]any
}Arguments and flags that matched no field on the command's config struct. A command reads these to support pass-through or dynamic flags. Args holds positional values with no matching numeric tag, and Options holds flags with no matching field.
func (c *ExecCommand) Run(_ cli.GlobalFlags, unknowns cli.Unknowns) error {
// forward everything after the known flags to the child process
return run(c.Inputs.Cmd, unknowns.Args...)
}