How to declare flags
This guide builds a fetch command that downloads a URL, and gives it one flag of each kind. If you’re new to CONGA, the quickstart builds a first command step by step.
Give a flag a type and a default
Section titled “Give a flag a type and a default”CONGA builds a command’s flags from the fields of its struct. The type of each flag field is a container, conga.OptionalFlag[...] for an optional flag or conga.RequiredFlag[...] for a required one. The type in the brackets is the type of the flag’s value, so a conga.OptionalFlag[int] field is an optional flag that takes an integer.
The field name sets the flag name in kebab case, so Retries becomes --retries, and the default tag sets the value used when the user doesn’t give the flag. Here fetch has three flags, plus the URL as a positional argument:
type Fetch struct { URL conga.RequiredArg[string] `help:"Address to download"` Output conga.OptionalFlag[string] `default:"-" help:"File to write"` Retries conga.OptionalFlag[int] `default:"3" help:"Attempts before giving up"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit per attempt"`}
func (f *Fetch) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "fetching %s to %s: %d tries, %s each\n", f.URL.Get(), f.Output.Get(), f.Retries.Get(), f.Timeout.Get())
return nil}
func main() { app := conga.New[Fetch]().Name("fetch")
if err := app.Run(); err != nil { app.Exit(err) }}The command’s Run method reads each flag’s value with the container’s Get method. Help shows each flag with its default:
$ fetch --helpUsage: fetch [flags] <url>
Arguments: <url> Address to download
Flags: --output="-" File to write --retries=3 Attempts before giving up --timeout=30s Time limit per attempt --help Show help --version Show version$ fetch https://example.comfetching https://example.com to -: 3 tries, 30s each$ fetch https://example.com --output page.html --retries 5 --timeout 2mfetching https://example.com to page.html: 5 tries, 2m0s eachA value that CONGA can’t convert to the flag’s type is a usage error, exit 2:
$ fetch https://example.com --timeout 30Error:fetch: error: invalid duration "30" (valid units: ms, s, m, h) for flag --timeoutErrorWhen the user repeats a flag, the last value wins. CONGA still converts every value, so a typo in an earlier one is an error, exit 2:
$ fetch https://example.com --retries 2 --retries 5fetching https://example.com to -: 5 tries, 30s each$ fetch https://example.com --retries two --retries 5Error:fetch: error: invalid integer value "two" for flag --retriesErrorA name tag replaces the derived name. For types CONGA doesn’t parse, see How to add custom flag types.
Add a short name and aliases
Section titled “Add a short name and aliases”A short tag adds a one-letter form, and an aliases tag adds more long names, separated by commas:
type Fetch struct { URL conga.RequiredArg[string] `help:"Address to download"` Output conga.OptionalFlag[string] `default:"-" help:"File to write" short:"o"` Retries conga.OptionalFlag[int] `aliases:"tries" default:"3" help:"Attempts before giving up"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit per attempt"`}$ fetch https://example.com -o page.html --tries 5fetching https://example.com to page.html: 5 tries, 30s eachHelp shows the short form beside the long one, and lists only the main name of an aliased flag:
Flags: -o, --output="-" File to write --retries=3 Attempts before giving upEvery short name and alias must be unique in the command and its ancestors. A clash fails at startup with ErrSchema, exit 1. Here Timeout also has short:"o":
fetch: error: struct Fetch field Timeout: schema error: duplicate flag: short flag -o (already declared by field Output)Let users turn off a default-on flag
Section titled “Let users turn off a default-on flag”A negatable tag on a bool flag adds a --no- form. Give it default:"true" for a behavior that is on unless the user turns it off:
type Fetch struct { URL conga.RequiredArg[string] `help:"Address to download"` Output conga.OptionalFlag[string] `default:"-" help:"File to write" short:"o"` Retries conga.OptionalFlag[int] `aliases:"tries" default:"3" help:"Attempts before giving up"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit per attempt"` Redirects conga.OptionalFlag[bool] `default:"true" help:"Follow redirects" negatable:"true"`}
func (f *Fetch) Run(ctx context.Context, session *conga.Session) error { // ... fmt.Fprintf(session.Stdout(), "follow redirects: %t\n", f.Redirects.Get()) // ...} --[no-]redirects Follow redirects [default: true]$ fetch https://example.com --no-redirectsfetching https://example.com to -: 3 tries, 30s eachfollow redirects: falseWhen both forms appear, the last one wins, so a user can override a wrapper script that passes --no-redirects:
$ fetch https://example.com --no-redirects --redirectsfetching https://example.com to -: 3 tries, 30s eachfollow redirects: true--redirects=false also works. Without the negatable tag, --no-redirects is an unknown flag. negatable on a non-bool flag fails at startup with ErrSchema, and so does a value other than true or false, such as negatable:"yes".
Count how often a flag is repeated
Section titled “Count how often a flag is repeated”conga.Counter is a flag container whose value is the number of times the user gives the flag. Short forms cluster, so -vvv counts three:
type Fetch struct { URL conga.RequiredArg[string] `help:"Address to download"` Output conga.OptionalFlag[string] `default:"-" help:"File to write" short:"o"` Retries conga.OptionalFlag[int] `aliases:"tries" default:"3" help:"Attempts before giving up"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit per attempt"` Redirects conga.OptionalFlag[bool] `default:"true" help:"Follow redirects" negatable:"true"` Verbose conga.Counter `help:"Print more detail; repeat for more" short:"v"`}
func (f *Fetch) Run(ctx context.Context, session *conga.Session) error { // ... fmt.Fprintf(session.Stdout(), "verbosity: %d\n", f.Verbose.Get()) // ...}$ fetch https://example.com -vvvfetching https://example.com to -: 3 tries, 30s eachverbosity: 3A cluster can end in a short flag that takes a value, as in -vvvo page.html. A counter counts occurrences and takes no value of its own, so --verbose=2, -v=2, and -vv=2 are usage errors:
$ fetch https://example.com --verbose=2Error:fetch: error: flag does not take a value: --verbose=2Error
Usage: fetch [flags] <url>
Run 'fetch --help' for more information.An environment variable or config file can still set the count, as a whole number of 0 or more. Here the builder also calls EnvPrefix("FETCH"):
$ FETCH_VERBOSE=2 fetch https://example.comverbosity: 2A count from the environment or a config file must be an unsigned whole number. A negative or signed value is ErrConfig, exit 1, because the value did not come from the command line. A counter starts at 0 and rejects a default tag at startup. Use OptionalFlag[int] when you need a different starting value, a level the user sets directly on the command line, or a negative value.
Accept a list of values
Section titled “Accept a list of values”A flag with a slice type, such as []int, collects every value the user gives. The user can repeat the flag, or separate values with commas:
type Fetch struct { URL conga.RequiredArg[string] `help:"Address to download"` Output conga.OptionalFlag[string] `default:"-" help:"File to write" short:"o"` Retries conga.OptionalFlag[int] `aliases:"tries" default:"3" help:"Attempts before giving up"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit per attempt"` Redirects conga.OptionalFlag[bool] `default:"true" help:"Follow redirects" negatable:"true"` Verbose conga.Counter `help:"Print more detail; repeat for more" short:"v"` RetryOn conga.OptionalFlag[[]int] `help:"Status codes to retry"` Header conga.OptionalFlag[[]string] `help:"Request header" sep:"none" short:"H"`}
func (f *Fetch) Run(ctx context.Context, session *conga.Session) error { // ... fmt.Fprintf(session.Stdout(), "retry on: %v\n", f.RetryOn.Get()) fmt.Fprintf(session.Stdout(), "headers: %q\n", f.Header.Get()) // ...}A header value can contain commas, so --header has sep:"none", which takes each value whole. sep can also name another separator, such as sep:";":
$ fetch https://example.com --retry-on 502,503 --retry-on 504 -H 'Accept: text/html, application/json' -H 'X-Trace: 1'fetching https://example.com to -: 3 tries, 30s eachretry on: [502 503 504]headers: ["Accept: text/html, application/json" "X-Trace: 1"]CONGA converts each value to the slice’s element type, so --retry-on 50x fails with invalid integer value "50x" for flag --retry-on, exit 2.
A list from the command line replaces a list from the environment or a config file. Here the builder also calls EnvPrefix("FETCH"):
$ FETCH_RETRY_ON=502,503 fetch https://example.com --retry-on 504fetching https://example.com to -: 3 tries, 30s eachretry on: [504]Accept key=value pairs
Section titled “Accept key=value pairs”A flag with the type map[string]string collects key=value pairs, repeated or separated by commas:
type Fetch struct { URL conga.RequiredArg[string] `help:"Address to download"` Output conga.OptionalFlag[string] `default:"-" help:"File to write" short:"o"` Retries conga.OptionalFlag[int] `aliases:"tries" default:"3" help:"Attempts before giving up"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit per attempt"` Redirects conga.OptionalFlag[bool] `default:"true" help:"Follow redirects" negatable:"true"` Verbose conga.Counter `help:"Print more detail; repeat for more" short:"v"` RetryOn conga.OptionalFlag[[]int] `help:"Status codes to retry"` Header conga.OptionalFlag[[]string] `help:"Request header" sep:"none" short:"H"` Form conga.OptionalFlag[map[string]string] `help:"Form field" short:"F"`}
func (f *Fetch) Run(ctx context.Context, session *conga.Session) error { // ... fmt.Fprintf(session.Stdout(), "form: %v\n", f.Form.Get()) // ...}$ fetch https://example.com -F name=ada -F lang=gofetching https://example.com to -: 3 tries, 30s eachform: map[lang:go name:ada]The value runs to the end of the word, so -F q=a=b sets q to a=b. A repeated key keeps its last value.
Unlike a list, a map from the command line merges with one from the environment or a config file key by key, and the command line wins for keys in both. With EnvPrefix("FETCH") again:
$ FETCH_FORM=name=ada,lang=go fetch https://example.com -F lang=rustfetching https://example.com to -: 3 tries, 30s eachform: map[lang:rust name:ada]Map values decode like single flag values, so a map[string]int or a map[string]time.Duration flag works the same way. For a map of your own type, see Use a custom type in a map flag.
Know what users see
Section titled “Know what users see”| What happens | When | Result |
|---|---|---|
| The user gives a value of the wrong type | Run | invalid duration "30" (valid units: ms, s, m, h) for flag --timeout, exit 2 |
| The user repeats a flag and an earlier value has the wrong type | Run | invalid integer value "two" for flag --retries, exit 2 |
| An environment variable holds a value of the wrong type | Run | invalid boolean value "no", expected true or false (or 1 or 0) for flag --redirects (from environment variable FETCH_REDIRECTS), exit 1 |
| The user misspells a flag | Run | unknown flag: --redirect (did you mean "--redirects"?), then usage, exit 2 |
The user gives --no- to a flag without negatable |
Run | unknown flag: --no-verbose, then usage, exit 2 |
| The user gives a counter a value | Run | flag does not take a value: --verbose=2, then usage, exit 2 |
| An environment variable gives a counter a negative or signed value | Run | invalid unsigned integer value "-1" for flag --verbose (from environment variable FETCH_VERBOSE), exit 1 |
The user gives a map entry without = |
Run | invalid key-value pair "name", expected KEY=VALUE for flag --form, exit 2 |
| A map flag’s value type has no parser | Startup | schema error: unsupported map value type net.IPNet; register a parser with app.RegisterType, exit 1 |
| Two flags share a short name or alias | Startup | schema error: duplicate flag: short flag -o (already declared by field Output), exit 1 |
negatable is on a flag that isn’t bool |
Startup | schema error: invalid struct tag: tag "negatable" is only valid on boolean flags, got time.Duration, exit 1 |
A Counter has a default tag |
Startup | schema error: invalid struct tag: tag "default" is not supported on counter flags; …, exit 1 |
Where to go next
Section titled “Where to go next”- Flags: every flag tag and rule.
- How to validate input: require flags, bound values, and reject conflicting flags.
- How to bind environment variables: set flags from the environment.
- How to customize help screens: group flags into sections and hide flags from help.