8.2 flag — Specification¶

A formal reference for the flag package: every defining function, the parse rules, the error semantics, and the *FlagSet method table. This file is for lookup, not for reading top to bottom.

Defining flags¶

All defining functions exist in two forms — pointer-returning and *Var — and on both flag.CommandLine (via the package-level shorthand) and *flag.FlagSet (as methods). The signatures are:

Behavior contract for every defining function:

• Registers the flag on the receiver *FlagSet (or flag.CommandLine).
• Panics with flag redefined: <name> if a flag of the same name is already registered on the same FlagSet.
• The flag's DefValue is set to the result of Value.String() called immediately after registration. For built-in types this is fmt.Sprintf("%v", default).
• For Func / BoolFunc, the registered Value is internally a type that calls the user's function on Set and returns "" from String.

The Value and Getter interfaces¶

type Value interface {
    String() string
    Set(string) error
}

type Getter interface {
    Value
    Get() interface{}
}

• String() is called for display in PrintDefaults and to capture DefValue at registration. Must work on a zero value (the package may call it on a nil-pointer receiver during type discovery).
• Set(s) is called once per occurrence of the flag on the command line. It must mutate the underlying value and return an error to reject the input.
• Get() (optional, via Getter) returns the typed value. Used by callers walking VisitAll who want the typed value rather than the string form.

Optional IsBoolFlag() bool method on a Value: returning true tells the parser this flag does not require an argument (the flag's mere presence sets it to "true"). Built-in bool flags implement this.

The boolFlag interface (unexported)¶

The parser tests for this interface internally:

type boolFlag interface {
    Value
    IsBoolFlag() bool
}

Any custom Value that returns true from IsBoolFlag() is treated as bool-style by the parser.

Parse rules¶

For arguments args[0:] passed to Parse:

1. If args[i] does not start with -, or is exactly -, parsing stops; args[i:] becomes positional arguments.
2. If args[i] is -- exactly, parsing stops; args[i+1:] becomes positional arguments.
3. Strip one or two leading - characters from args[i]. (Both -name and --name are accepted, equivalently.)
4. Find the first =. If present, split on it: the part before is the flag name, the part after is the value, and parsing for this token is complete.
5. If no =:
6. Look up the flag by the remaining name.
7. If the flag's Value implements IsBoolFlag() bool returning true, the value is "true".
8. Otherwise, the value is args[i+1], and i advances by 2 instead of 1. If no args[i+1] exists, error with flag needs an argument.
9. Call Value.Set(value). On error, surface as invalid value "<value>" for flag -<name>: <err>.
10. Continue with args[i+1] (or args[i+2] after consuming a space-separated value).

Special token: -h and --help, when no flag of that name is registered, call Usage and return flag.ErrHelp from Parse.

Error semantics by ErrorHandling mode¶

flag.NewFlagSet(name, mode) accepts:

The global flag.CommandLine is constructed with ExitOnError.

Errors returned by Parse (in ContinueOnError mode):

errors.Is(err, flag.ErrHelp) is the only sentinel comparison the package documents. The other messages are formatted strings — match on substring if you must, but prefer not matching at all.

*FlagSet methods¶

The package-level functions flag.X are aliases for flag.CommandLine.X. There is no flag.SetOutput shorthand; use flag.CommandLine.SetOutput.

The Flag struct¶

type Flag struct {
    Name     string // flag name, no leading "-"
    Usage    string // help text
    Value    Value  // underlying Value (call Get() if it's also a Getter)
    DefValue string // default value as a string, captured at registration
}

These four fields are the entire public surface of a registered flag. DefValue is a string for display; the actual default lives in Value (and was stringified once at registration time).

Type-coercion rules per built-in¶

flag.Var performs no coercion — your Value.Set does whatever parsing it wants.

Package-level globals¶

What the package does not provide¶

• Required flags (build with Visit after Parse).
• Short/long flag pairs (register two flags sharing a Var).
• Abbreviation matching (every name must be exact).
• Environment-variable fallback (compose with os.LookupEnv before Parse).
• Subcommand dispatch (build with multiple *FlagSet and a switch on os.Args).
• Mutual exclusion or dependency rules between flags (validate after Parse).
• Shell completions (build with a hidden subcommand or graduate to cobra).
• Hidden / deprecated flag attributes (filter in custom Usage).

Compatibility notes¶

• flag.Func added in Go 1.16.
• flag.TextVar added in Go 1.19.
• flag.BoolFunc added in Go 1.21.
• All other functions and methods in this reference have been stable since Go 1.0 with no signature changes.