How to validate input
This guide builds an export command that sends records to a file or a URL, and adds one kind of check at each step. Each check runs before Run. A command-line value that fails one is a usage error; the program prints the problem and exits with status 2. A value from the environment, a config file, or a default tag classifies under ErrConfig instead and exits with status 1. A failed group check (xor, oneof, and) is a usage error when one of its flags came from the command line, and ErrConfig when they all came from the environment or a config file.
Require a flag
Section titled “Require a flag”Declare the field as a conga.RequiredFlag[...] container, in place of conga.OptionalFlag[...]:
type Export struct { Token conga.RequiredFlag[string] `help:"API token"` Format conga.OptionalFlag[string] `default:"json" help:"Output format"`}
func (e *Export) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "exporting as %s\n", e.Format.Get())
return nil}
func main() { app := conga.New[Export]().Name("export").EnvPrefix("EXPORT")
if err := app.Run(); err != nil { app.Exit(err) }}$ exportError:export: error: missing required flag: --tokenError
Usage: export --token=STRING [flags]
Run 'export --help' for more information.The usage line shows --token=STRING outside [flags]. EnvPrefix("EXPORT") gives each flag an environment variable, EXPORT_TOKEN for this one. A value there, or in a config file when the app reads one, also satisfies a required flag, so the user can leave --token off the command line. A required flag can’t have a default tag.
Allow only a set of values
Section titled “Allow only a set of values”An enum tag lists the values the flag accepts, separated by commas:
type Export struct { Token conga.RequiredFlag[string] `help:"API token"` Format conga.OptionalFlag[string] `default:"json" enum:"json,csv,yaml" help:"Output format"`}$ export --token abc --format xmlError:export: error: invalid value "xml" (must be one of: json, csv, yaml) for flag --formatErrorHelp lists the values after the flag’s help text:
--format="json" Output format [enum: json, csv, yaml]Shell completion offers the same values.
Bound numbers, lengths, and counts
Section titled “Bound numbers, lengths, and counts”Three tags put bounds on a value, written as min..max. Timeout is a time.Duration, so the file now imports time:
rangebounds a number, a duration, or a size.lenbounds the length of a string.itemsbounds the number of values in a list or a map.
type Export struct { Token conga.RequiredFlag[string] `help:"API token"` Format conga.OptionalFlag[string] `default:"json" enum:"json,csv,yaml" help:"Output format"` Limit conga.OptionalFlag[int] `default:"100" help:"Records to export" range:"1..1000"` Timeout conga.OptionalFlag[time.Duration] `default:"30s" help:"Time limit" range:"1s..5m"` Label conga.OptionalFlag[string] `help:"Label for the export" len:"3..20"` Fields conga.OptionalFlag[[]string] `help:"Fields to include" items:"1..5"`}Each bound has its own message:
$ export --token abc --limit 0Error:export: error: value 0 is out of range [1..1000] for flag --limitError$ export --token abc --timeout 10mError:export: error: value 10m0s is out of range [1s..5m] for flag --timeoutError$ export --token abc --label abError:export: error: value "ab" length 2 is out of range [3..20] for flag --labelError$ export --token abc --fields a,b,c,d,e,fError:export: error: item count 6 is out of range [1..5] for flag --fieldsErrorHelp shows each bound:
--limit=100 Records to export [1..1000] --timeout=30s Time limit [1s..5m] --label=STRING Label for the export [len: 3..20] --fields=STRING,... Fields to include [items: 1..5]An optional flag with a bound can still be left out. Make it a required flag when it must be given. Either side of a bound can be left open, as in range:"1..", and a single number, as in items:"5", means exactly that many.
Reject flags that conflict
Section titled “Reject flags that conflict”Give flags the same xor group name, and the user can give at most one of them:
type Export struct { // ... Gzip conga.OptionalFlag[bool] `help:"Compress with gzip" xor:"compression"` Zstd conga.OptionalFlag[bool] `help:"Compress with zstd" xor:"compression"`}$ export --token abc --gzip --zstdError:export: error: flags --gzip and --zstd are mutually exclusiveError
Usage: export --token=STRING [flags]
Run 'export --help' for more information.A flag counts as given when the user writes it at all, whatever its value, so --gzip=false --zstd fails the same way. Help names the other flag of the group on each line:
$ export --help | grep -e --gzip -e --zstd --gzip Compress with gzip [env: EXPORT_GZIP] [xor: --zstd] --zstd Compress with zstd [env: EXPORT_ZSTD] [xor: --gzip]A flag set in the environment counts as given too, and the error names its variable:
$ EXPORT_GZIP=true export --token abc --zstdError:export: error: flags --gzip (from environment variable EXPORT_GZIP) and --zstd are mutually exclusiveError
Usage: export --token=STRING [flags]
Run 'export --help' for more information.When both flags come from the environment, the user typed nothing that caused the conflict. The program prints the error without usage and exits with status 1:
$ EXPORT_GZIP=true EXPORT_ZSTD=true export --token abcError:export: error: flags --gzip (from environment variable EXPORT_GZIP) and --zstd (from environment variable EXPORT_ZSTD) are mutually exclusiveErrorDemand exactly one of a group
Section titled “Demand exactly one of a group”Give flags the same oneof group name, and the user must give exactly one of them. Here the export goes to a file or a URL:
type Export struct { // ... ToFile conga.OptionalFlag[string] `help:"Write to a file" oneof:"destination" placeholder:"PATH"` ToURL conga.OptionalFlag[string] `help:"Upload to a URL" oneof:"destination" placeholder:"URL"`}Leaving both out fails:
$ export --token abcError:export: error: missing required flag: one of --to-file, --to-urlError
Usage: export --token=STRING (--to-file=PATH | --to-url=URL) [flags]
Run 'export --help' for more information.Giving both fails too:
$ export --token abc --to-file out.json --to-url https://example.com/uploadError:export: error: flags --to-file and --to-url are mutually exclusiveError
Usage: export --token=STRING (--to-file=PATH | --to-url=URL) [flags]
Run 'export --help' for more information.The usage line shows the group as (--to-file=PATH | --to-url=URL). A member of a oneof group can’t have a default tag.
Require flags together
Section titled “Require flags together”Give flags the same and group name, and the user must give all of them or none, from any mix of the command line, the environment, and a config file:
type Export struct { // ... Username conga.OptionalFlag[string] `and:"auth" help:"Proxy user name"` Password conga.OptionalFlag[string] `and:"auth" help:"Proxy password"`}$ export --token abc --to-file out.json --username adaError:export: error: flag --username must be given together with --passwordError
Usage: export --token=STRING (--to-file=PATH | --to-url=URL) [flags]
Run 'export --help' for more information.$ export --token abc --to-file out.json --username ada --password s3cretexporting as jsonHelp names the other flag of the group on each line:
$ export --help | grep -e --username -e --password --username=STRING Proxy user name [env: EXPORT_USERNAME] [and: --password] --password=STRING Proxy password [env: EXPORT_PASSWORD] [and: --username]A password left in EXPORT_PASSWORD counts as given, so a run without --username fails. The program prints the error without usage and exits with status 1:
$ EXPORT_PASSWORD=s3cret export --token abc --to-file out.jsonError:export: error: flag --password (from environment variable EXPORT_PASSWORD) must be given together with --usernameErrorCheck values against each other
Section titled “Check values against each other”When a rule involves more than one value, or more than a tag can say, implement conga.Validator on the command:
type Validator interface { Validate(ctx context.Context, session *Session) error}Here the export covers a date range, and the last day can’t come before the first. The file now also imports errors:
type Export struct { // ... Since conga.OptionalFlag[string] `default:"2026-01-01" help:"First day to export (YYYY-MM-DD)"` Until conga.OptionalFlag[string] `default:"2026-01-31" help:"Last day to export (YYYY-MM-DD)"`}
func (e *Export) Validate(ctx context.Context, session *conga.Session) error { since, err := time.Parse(time.DateOnly, e.Since.Get()) if err != nil { return fmt.Errorf("--since %q is not a date (YYYY-MM-DD)", e.Since.Get()) }
until, err := time.Parse(time.DateOnly, e.Until.Get()) if err != nil { return fmt.Errorf("--until %q is not a date (YYYY-MM-DD)", e.Until.Get()) }
if until.Before(since) { return errors.New("--until must not be before --since") }
return nil}An error from Validate is a usage error, like a failed tag check:
$ export --token abc --to-file out.json --since 2026-02-01Error:export: error: --until must not be before --sinceError
Usage: export --token=STRING (--to-file=PATH | --to-url=URL) [flags]
Run 'export --help' for more information.Validate runs after every tag check has passed, and before Run and any lifecycle hook, so it can trust that the flags hold valid values and the program has opened nothing yet. Write the message the user should see. CONGA prints it after export: error:.
Know what users see
Section titled “Know what users see”EnvPrefix("EXPORT") gives each flag a variable such as EXPORT_LIMIT.
| What the user does | Result |
|---|---|
| Leaves out a required flag | missing required flag: --token, then usage, exit 2 |
| Sets the required flag in the environment only | Works |
Gives a value outside the enum list |
invalid value "xml" (must be one of: json, csv, yaml) for flag --format, exit 2 |
| Gives a value outside a bound | value 0 is out of range [1..1000] for flag --limit, exit 2 |
| Sets a value outside a bound in the environment | value 5000 is out of range [1..1000] for flag --limit (from environment variable EXPORT_LIMIT), exit 1 |
Gives two flags from one xor group |
flags --gzip and --zstd are mutually exclusive, then usage, exit 2 |
Gives --gzip=false with --zstd |
The same error: --gzip counts as given |
Sets one xor flag in the environment and gives the other on the command line |
flags --gzip (from environment variable EXPORT_GZIP) and --zstd are mutually exclusive, then usage, exit 2 |
Sets both xor flags in the environment |
flags --gzip (from environment variable EXPORT_GZIP) and --zstd (from environment variable EXPORT_ZSTD) are mutually exclusive, exit 1 |
Gives no flag from a oneof group |
missing required flag: one of --to-file, --to-url, then usage, exit 2 |
Sets one oneof flag in the environment and gives the other on the command line |
flags --to-file and --to-url (from environment variable EXPORT_TO_URL) are mutually exclusive, then usage, exit 2 |
Sets both oneof flags in the environment |
flags --to-file (from environment variable EXPORT_TO_FILE) and --to-url (from environment variable EXPORT_TO_URL) are mutually exclusive, exit 1 |
Gives only part of an and group |
flag --username must be given together with --password, then usage, exit 2 |
Gives --username and sets the password in the environment |
Works |
| Sets only the password in the environment | flag --password (from environment variable EXPORT_PASSWORD) must be given together with --username, exit 1 |
Gives values that Validate rejects |
The returned message, then usage, exit 2 |
Leaves out a flag whose default is outside its bound |
value 5000 is out of range [1..1000] for flag --limit (from default value), exit 1, on every such run |
Where to go next
Section titled “Where to go next”- Flags: every validation tag, and the group rules.
- Bounds syntax: open bounds, and bounds for sizes and durations.
- How to declare flags: the flag types these checks apply to.
- About error reporting: why a failed check exits with status 2.