Skip to content

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.

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:

main.go
package main
import (
"context"
"fmt"
"time"
"github.com/conga-sh/conga"
)
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:

Terminal window
$ fetch --help
Usage:
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
Terminal window
$ fetch https://example.com
fetching https://example.com to -: 3 tries, 30s each
Terminal window
$ fetch https://example.com --output page.html --retries 5 --timeout 2m
fetching https://example.com to page.html: 5 tries, 2m0s each

A value that CONGA can’t convert to the flag’s type is a usage error, exit 2:

Terminal window
$ fetch https://example.com --timeout 30
Error:fetch: error: invalid duration "30" (valid units: ms, s, m, h) for flag --timeout

When 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:

Terminal window
$ fetch https://example.com --retries 2 --retries 5
fetching https://example.com to -: 5 tries, 30s each
Terminal window
$ fetch https://example.com --retries two --retries 5
Error:fetch: error: invalid integer value "two" for flag --retries

A name tag replaces the derived name. For types CONGA doesn’t parse, see How to add custom flag types.

A short tag adds a one-letter form, and an aliases tag adds more long names, separated by commas:

main.go
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"`
}
Terminal window
$ fetch https://example.com -o page.html --tries 5
fetching https://example.com to page.html: 5 tries, 30s each

Help 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 up

Every 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)

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:

main.go
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]
Terminal window
$ fetch https://example.com --no-redirects
fetching https://example.com to -: 3 tries, 30s each
follow redirects: false

When both forms appear, the last one wins, so a user can override a wrapper script that passes --no-redirects:

Terminal window
$ fetch https://example.com --no-redirects --redirects
fetching https://example.com to -: 3 tries, 30s each
follow 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".

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:

main.go
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())
// ...
}
Terminal window
$ fetch https://example.com -vvv
fetching https://example.com to -: 3 tries, 30s each
follow redirects: true
verbosity: 3

A 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:

Terminal window
$ fetch https://example.com --verbose=2
Error:fetch: error: flag does not take a value: --verbose=2
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"):

Terminal window
$ FETCH_VERBOSE=2 fetch https://example.com
fetching https://example.com to -: 3 tries, 30s each
follow redirects: true
verbosity: 2

A 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.

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:

main.go
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:";":

Terminal window
$ 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 each
follow redirects: true
verbosity: 0
retry 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"):

Terminal window
$ FETCH_RETRY_ON=502,503 fetch https://example.com --retry-on 504
fetching https://example.com to -: 3 tries, 30s each
follow redirects: true
verbosity: 0
retry on: [504]
headers: []

A flag with the type map[string]string collects key=value pairs, repeated or separated by commas:

main.go
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())
// ...
}
Terminal window
$ fetch https://example.com -F name=ada -F lang=go
fetching https://example.com to -: 3 tries, 30s each
follow redirects: true
verbosity: 0
retry on: []
headers: []
form: 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:

Terminal window
$ FETCH_FORM=name=ada,lang=go fetch https://example.com -F lang=rust
fetching https://example.com to -: 3 tries, 30s each
follow redirects: true
verbosity: 0
retry on: []
headers: []
form: 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.

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