Tags
Every struct tag a command's config fields can carry.
A command's config struct is driven entirely by field tags. Some tags name a field for input lookup, and some configure how a field is bound, validated, or shown. This page lists every tag the framework reads.
Lookup tags
These name a field so an argument or flag can reach it.
| Tag | Purpose |
|---|---|
arg:"0" | A positional argument, by zero-based index. |
arg:"name" | A named flag, --name. |
short:"n" | A single-character alias, -n. |
env:"NAME" | Binds an environment variable to the field. |
A nested struct field is reached by its dotted path, gluing the parent tag to the child (--database.host). An env tag on a nested field is glued with _ (DATABASE_HOST).
Behavior tags
These configure a field regardless of how it is named.
| Tag | Purpose |
|---|---|
default:"..." | Value used when nothing else supplies one. Never overrides real input. |
sep:"..." | Separator for splitting a single string into a slice field. Defaults to ,, and sep:"" disables splitting. |
rules:"..." | Space-separated validation rules, arguments after a colon (rules:"required oneof:a,b"). |
help:"..." | One-line help text shown next to the flag or argument. |
secret:"true" | Masks the field's resolved value in --help-values output. |
Validation rules
Rules are declared in the rules: tag. Two are built in.
requiredfails when a field has no input, no default, and a zero value.oneof:a,b,crestricts a field to one of the listed values. Pair it withrequiredto force both presence and membership.
Validation is powered by the structs module, which cli builds on. See its validation guide for custom rules and the full rule model.
Note
The lookup tag priority a command uses is arg, short, then the encoding tags (json, yaml). A field with no lookup tag falls back to its Go field name.