Domain types
Types in the root conga package and the topical network and system packages implement Predictable interfaces — they carry their own completion behavior alongside coercion and validation. Using them makes flags and arguments complete automatically in all six shells. To author custom flag types, see How to add custom flag types.
Filesystem types
Section titled “Filesystem types”| Type | Coercion / validation | Completes as |
|---|---|---|
conga.File |
Expands ~ and environment variables; capability tags constrain the path |
File paths (or per capability tags) |
conga.Dir |
Expands ~ and environment variables; existing requires a directory |
Directories |
File accepts the capability tags existing, stdin, stdout, executable, symlink, and glob. The struct tag reference defines each tag, its mutual exclusions, and the schema-build rules.
type Convert struct { Input conga.OptionalFlag[conga.File] `existing:"true" stdin:"true"` Output conga.OptionalFlag[conga.File] `stdout:"true"` Tool conga.OptionalFlag[conga.File] `executable:"true"` Recipe conga.OptionalFlag[conga.File] `glob:"*.yaml,Makefile"`}All filesystem capability checks run during the validation phase on the final resolved value, after the configuration cascade. A failed check is ErrValidation for a command-line value and ErrConfig for a value from the environment, a config file, or a default tag. File with executable:"true" also resolves a bare name on $PATH while converting the text, and turns any other path, including ./tool, into an absolute path against the working directory. The $PATH lookup is conversion-time, so a miss is ErrCoerce for a command-line value and ErrConfig for a value from another source. Errors and exit codes states the rule.
Content and I/O types
Section titled “Content and I/O types”| Type | Behavior |
|---|---|
conga.FileContent |
Reads the file into memory during parsing; accepts - for stdin; 16 MiB limit; a scalar flag can be given only once on the command line, and the type is rejected on bootstrap fields |
conga.ByteSize |
Parses "10MiB", "1.5GB", "500KiB", and exact bytes; Bytes() returns int64; strict case-sensitive units. See Byte size parsing and Byte size rendering |
type Upload struct { Payload conga.FileContent Budget conga.ByteSize `default:"10MiB"`}
func (u *Upload) Run(ctx context.Context, session *conga.Session) error { limit := u.Budget.Bytes() // 10485760 ...}Byte size parsing
Section titled “Byte size parsing”ByteSize input is strict and case-sensitive. It accepts exact byte counts, SI metric units ending in B, and IEC binary units:
| Form | Examples | Meaning |
|---|---|---|
| Exact bytes | 1024, 500B |
Byte counts |
| Decimal | kB, MB, GB, TB, PB, EB |
Powers of 1000 |
| Binary | KiB, MiB, GiB, TiB, PiB, EiB |
Powers of 1024 |
The numeric prefix is digits with an optional fraction whose contribution resolves exactly to bytes (1.5GB, 0.5GiB), and a sub-byte remainder such as 0.1GiB is rejected. Naked unit suffixes without B (10G, 512Mi) and lowercase casings (mb, kib) are rejected to prevent ambiguity. kB is always 1000 bytes and KiB is always 1024. KB is rejected as ambiguous because it denotes 1000 bytes in SI usage and 1024 bytes in legacy usage. An unknown unit error lists the units the field accepts. Text input must be non-negative, and the largest size is 9223372036854775807 bytes (one byte under 8EiB). A larger size, such as 10000PB, fails with byte size "10000PB" is out of range (max 9223372036854775807B).
Byte size rendering
Section titled “Byte size rendering”A value renders in its display family. A display tag of binary or decimal forces that family, and input, the default, uses the family of the unit the value was decoded from. Rendering picks the largest unit of that family that divides the byte count exactly, or exact bytes when no unit divides it:
| Input | display tag |
Output |
|---|---|---|
1.5GB |
input (default) |
1500MB |
0.5GiB |
input |
512MiB |
1024 |
input |
1024B |
1.000000001GB |
input |
1000000001B |
1.5GB |
binary |
1500000000B |
1024kB |
binary |
1000KiB |
1000KiB |
decimal |
1024kB |
1073741824 |
binary |
1GiB |
| zero value | any | 0B |
Byte size tags
Section titled “Byte size tags”Two struct tags tune acceptance and display:
| Tag | Values | Effect |
|---|---|---|
units |
binary, decimal, both (default) |
Restricts the accepted unit families; a parsed unit outside the allowed family is a coercion error. Exact byte counts (B suffix or bare) are family-neutral and accepted by both. |
display |
binary, decimal, input (default) |
Forces the render family; input echoes the entered unit family. |
An unrecognized tag value fails at schema build, and range bounds parse under the same tags (see Bounds syntax).
type Cache struct { Memory conga.ByteSize `units:"binary"`}Byte size comparison
Section titled “Byte size comparison”Compare ByteSize values with Equal, order with Compare, and retrieve raw magnitudes with Bytes(). The type is non-comparable via Go’s == operator to preserve unit-family independence.
File streaming
Section titled “File streaming”File streams through Reader() and Writer(), which return io.ReadCloser and io.WriteCloser. When the value is -, Reader() wraps the app’s standard input and Writer() its standard output (the streams set with App.Stdin and App.Stdout, which default to os.Stdin and os.Stdout). A File that no app bound uses os.Stdin and os.Stdout. The wrappers absorb Close(), so callers can always defer Close(). Stat() exposes the file metadata, and IsStdio() reports the - case so commands can skip filesystem-only side effects (backups, atomic renames) and route diagnostics away from a stdout payload stream. Standard input can be read once per run: at most one value may be - for a FileContent or for a File with stdin, counting every flag, positional argument, slice item, and source, and a second one fails before either reads with stdin can only be read once (--input and --header both use "-"). Two command-line values are a usage error (ErrValidation, exit 2); a conflict involving an environment, configuration, or default value classifies under ErrConfig (exit 1). Any number of stdout values may be -. Reading beyond these helpers is the caller’s responsibility (io.ReadAll(f.Reader())), and FileContent is the bounded whole-file shortcut.
func (c *Convert) Run(ctx context.Context, session *conga.Session) error { writer, err := c.Output.Get().Writer() if err != nil { return err } defer writer.Close()
reader, err := c.Input.Get().Reader() if err != nil { return err } defer reader.Close()
_, err = io.Copy(writer, reader)
return err}Topical domain packages
Section titled “Topical domain packages”The domain packages (network, system, timezone) bundle value types, autocompletion predictors, and standard library bindings. Declaring a field with a domain type such as network.Host or system.User enables automatic coercion and autocompletion. When a field uses standard library types (*net.Interface, *time.Location), register the corresponding binding with app.Use(...).
| Package | Domain types | Standard library binding |
|---|---|---|
network |
Host, Port, HTTPMethod, HTTPStatus, MIMEType, NetInterface |
network.RegisterInterface (alias network.RegisterNetInterface) for *net.Interface |
system |
User, Group, Signal, PID, Process, EnvVar, Locale |
system.RegisterUser (*user.User), system.RegisterGroup (*user.Group), system.RegisterSignal (syscall.Signal) |
timezone |
– | timezone.RegisterLocation (*time.Location) |
Each package also exports its predictors as standalone constructors, network.Hosts(), network.NetInterfaces(), system.Signals(), system.Users(), system.ProcessIDs() (alias system.PIDs()), system.ProcessNames() (alias system.Processes()), system.Locales(), system.EnvVars(), and timezone.Timezones().
Domain types in network and system implement encoding.TextMarshaler with value receivers, supporting canonical text formatting and serialization.
type Deploy struct { Host conga.OptionalFlag[network.Host] `help:"Target host"` Port conga.OptionalFlag[network.Port] `help:"Target port"` User conga.OptionalFlag[system.User] `help:"Run as user"` Method conga.OptionalFlag[network.HTTPMethod] `help:"HTTP method"`}
type Legacy struct { Iface conga.OptionalFlag[*net.Interface] `help:"Network interface"` Zone conga.OptionalFlag[*time.Location] `help:"Server timezone"`}
app := conga.New[Legacy](). Use(network.RegisterInterface, timezone.RegisterLocation)A domain-type coercion failure classifies under conga.ErrCoerce when the value came from the command line and under conga.ErrConfig when it came from the environment, a config file, or a default tag. The message reports the flag name, the failure reason, and the value’s source. Methods that query host state (network.Host.LookupIP, network.NetInterface.Interface, system.User.Lookup, system.Group.Lookup) return a descriptive error naming the failed lookup for blank input, or the wrapped OS/network error otherwise.
Default help text
Section titled “Default help text”An explicit help:"..." tag replaces the type-derived description. Without one, these types describe themselves in the help screen:
| Field type | Declared tags | Default help |
|---|---|---|
conga.File |
– | Path to a file |
conga.File |
existing:"true" |
Path to an existing file |
conga.File |
stdin:"true" |
Path to a file or '-' for stdin |
conga.File |
stdout:"true" |
Path to a file or '-' for stdout |
conga.File |
executable:"true" |
Path to an executable |
conga.File |
symlink:"true" |
Path to a symbolic link |
conga.File |
glob:"<patterns>" |
Path to a file matching '<patterns>' |
conga.Dir |
– | Path to a directory |
conga.Dir |
existing:"true" |
Path to an existing directory |
conga.FileContent |
– | Path to a file (or '-' for stdin) |
conga.ByteSize |
– | Byte size (e.g., 10MiB, 1.5GB, 500KiB) |
conga.ByteSize |
units:"binary" |
Byte size in binary units (e.g., 10KiB, 512MiB) |
conga.ByteSize |
units:"decimal" |
Byte size in decimal units (e.g., 10kB, 512MB) |
network.Host |
– | Host (hostname, domain, or IP address) |
network.HTTPMethod |
– | HTTP method (GET, POST, PUT, DELETE, ...) |
network.HTTPStatus |
– | HTTP status code (100-599, e.g. 200, 404) |
network.MIMEType |
– | MIME type (e.g. application/json) |
network.NetInterface |
– | Network interface (e.g. eth0, lo) |
network.Port |
– | Port (1-65535, or a service name like "http") |
system.EnvVar |
– | Environment variable name (e.g. PATH) |
system.Group |
– | System group name |
system.Locale |
– | Locale identifier (e.g. en_US.UTF-8) |
system.PID |
– | Process ID (a positive integer) |
system.Process |
– | Process executable name (e.g. postgres) |
system.Signal |
– | Signal name or number (e.g. SIGTERM, 9) |
system.User |
– | System username |
time.Duration renders Duration (e.g., 300ms, 2m45s, 1h). The container types delegate to their value type, so OptionalFlag[conga.File] and RequiredArg[conga.Dir] use the descriptions above. After the description, the engine appends [default: ...], [env: ...], constraint hints such as [1..65535] or [items: 2..3], and [enum: ...] where the field declares them. Referencing the matching {{...}} variable in the field’s help tag suppresses that automatic hint (see Help variables).
Domain type interfaces
Section titled “Domain type interfaces”| Interface | Method | Purpose |
|---|---|---|
Predictable |
Predict() predict.Predictor |
Parameterless self-completion candidates; consulted when completing a field of the type |
TagAwarePredictable |
Predict(tags FieldTags) predict.Predictor |
Tag-tailored candidates; preferred when both forms are implemented |
HelpProvider |
Help() string |
Parameterless default help description |
TagAwareHelpProvider |
Help(tags FieldTags) string |
Tag-tailored default help; preferred when both forms are implemented |
TagSpecProvider |
TagSpecs() []TagSpec |
Registers the custom field tags the type accepts |
ContextAwareTextUnmarshaler |
UnmarshalTextWithContext(text []byte, decodeContext DecodeContext) error |
Decode-time access to the declared tags and configured streams |
SelfValidator |
Validate(ctx context.Context) error |
Post-cascade validation of the resolved value |
Implement exactly one form of each tag-aware pair. Filesystem-derived types can additionally participate in shell-side filtering through FileFilterable, DirFilterable, and PathFilterable.
Decoding order
Section titled “Decoding order”CONGA decodes a scalar flag, argument, environment, or config value into type U, and each element of a slice and each key and value of a map, with the first of these that applies:
- A
conga.TypeParser[U]registered withapp.RegisterType. UnmarshalTextWithContexton*U(ContextAwareTextUnmarshaler).UnmarshalTexton*U(encoding.TextUnmarshaler).- Built-in parsing for
string,bool, signed and unsigned integers,time.Duration, floats, andurl.URL/*url.URL.
Schema build rejects a flag or positional argument whose type, slice element type, or map key or value type none of these decode: schema error: unsupported type <U>, exit 1, naming the registration that fixes it. An error from steps 1 to 3 inherits the value’s source: the flag name and origin are appended to its message, and the category follows the source.
A slice or map type whose pointer implements one of the unmarshaler interfaces, such as net.IP, is one value, decoded whole by step 2 or 3. app.RegisterType panics for any slice or map type, because the binder decodes collections element by element and entry by entry.
Custom tags
Section titled “Custom tags”TagSpecs() returns one conga.TagSpec per tag the type accepts on its fields:
| Field | Type | Meaning |
|---|---|---|
Name |
string |
The struct tag key |
Kind |
conga.TagKind |
conga.TagKindBool (value must be true or false) or conga.TagKindString |
Validate |
func(value string) error |
Optional check of a TagKindString value at schema build |
Excludes |
[]string |
Tag keys that can’t be declared on the same field as this one |
Schema build rejects, with ErrSchema, a tag that no TagSpec of the field’s type names, a TagKindBool tag with another value, a Validate error, and a tag declared together with one its Excludes lists. app.AllowTags exempts listed foreign keys.
UnmarshalTextWithContext receives a conga.DecodeContext:
| Field | Type | Meaning |
|---|---|---|
Tags |
conga.FieldTags |
The owning field’s declared custom tags; nil when it declares none |
Stdin |
io.Reader |
The App’s configured stdin (App.Stdin); nil means os.Stdin |
Stdout |
io.Writer |
The App’s configured stdout (App.Stdout); nil means os.Stdout |
FieldTags.Has(key) reports whether the field declares the tag, Bool(key) whether it is "true", and String(key) its value, "" when absent. The zero DecodeContext behaves like plain UnmarshalText.
type ContextAwareTextUnmarshaler interface { UnmarshalTextWithContext(text []byte, decodeContext DecodeContext) error}
type SelfValidator interface { Validate(ctx context.Context) error}
type TagSpecProvider interface { TagSpecs() []TagSpec}