Skip to content

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.

Declare the field as a conga.RequiredFlag[...] container, in place of conga.OptionalFlag[...]:

main.go
package main
import (
"context"
"fmt"
"github.com/conga-sh/conga"
)
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)
}
}
Terminal window
$ export
Error:export: error: missing required flag: --token
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.

An enum tag lists the values the flag accepts, separated by commas:

main.go
type Export struct {
Token conga.RequiredFlag[string] `help:"API token"`
Format conga.OptionalFlag[string] `default:"json" enum:"json,csv,yaml" help:"Output format"`
}
Terminal window
$ export --token abc --format xml
Error:export: error: invalid value "xml" (must be one of: json, csv, yaml) for flag --format

Help lists the values after the flag’s help text:

--format="json" Output format [enum: json, csv, yaml]

Shell completion offers the same values.

Three tags put bounds on a value, written as min..max. Timeout is a time.Duration, so the file now imports time:

  • range bounds a number, a duration, or a size.
  • len bounds the length of a string.
  • items bounds the number of values in a list or a map.
main.go
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:

Terminal window
$ export --token abc --limit 0
Error:export: error: value 0 is out of range [1..1000] for flag --limit
Terminal window
$ export --token abc --timeout 10m
Error:export: error: value 10m0s is out of range [1s..5m] for flag --timeout
Terminal window
$ export --token abc --label ab
Error:export: error: value "ab" length 2 is out of range [3..20] for flag --label
Terminal window
$ export --token abc --fields a,b,c,d,e,f
Error:export: error: item count 6 is out of range [1..5] for flag --fields

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

Give flags the same xor group name, and the user can give at most one of them:

main.go
type Export struct {
// ...
Gzip conga.OptionalFlag[bool] `help:"Compress with gzip" xor:"compression"`
Zstd conga.OptionalFlag[bool] `help:"Compress with zstd" xor:"compression"`
}
Terminal window
$ export --token abc --gzip --zstd
Error:export: error: flags --gzip and --zstd are mutually exclusive
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:

Terminal window
$ 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:

Terminal window
$ EXPORT_GZIP=true export --token abc --zstd
Error:export: error: flags --gzip (from environment variable EXPORT_GZIP) and --zstd are mutually exclusive
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:

Terminal window
$ EXPORT_GZIP=true EXPORT_ZSTD=true export --token abc
Error:export: error: flags --gzip (from environment variable EXPORT_GZIP) and --zstd (from environment variable EXPORT_ZSTD) are mutually exclusive

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:

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

Terminal window
$ export --token abc
Error:export: error: missing required flag: one of --to-file, --to-url
Usage:
export --token=STRING (--to-file=PATH | --to-url=URL) [flags]
Run 'export --help' for more information.

Giving both fails too:

Terminal window
$ export --token abc --to-file out.json --to-url https://example.com/upload
Error:export: error: flags --to-file and --to-url are mutually exclusive
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.

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:

main.go
type Export struct {
// ...
Username conga.OptionalFlag[string] `and:"auth" help:"Proxy user name"`
Password conga.OptionalFlag[string] `and:"auth" help:"Proxy password"`
}
Terminal window
$ export --token abc --to-file out.json --username ada
Error:export: error: flag --username must be given together with --password
Usage:
export --token=STRING (--to-file=PATH | --to-url=URL) [flags]
Run 'export --help' for more information.
Terminal window
$ export --token abc --to-file out.json --username ada --password s3cret
exporting as json

Help names the other flag of the group on each line:

Terminal window
$ 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:

Terminal window
$ EXPORT_PASSWORD=s3cret export --token abc --to-file out.json
Error:export: error: flag --password (from environment variable EXPORT_PASSWORD) must be given together with --username

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:

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

Terminal window
$ export --token abc --to-file out.json --since 2026-02-01
Error:export: error: --until must not be before --since
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:.

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