Skip to content

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.

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.

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

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

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

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"`
}

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 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
}

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.

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

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.

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:

  1. A conga.TypeParser[U] registered with app.RegisterType.
  2. UnmarshalTextWithContext on *U (ContextAwareTextUnmarshaler).
  3. UnmarshalText on *U (encoding.TextUnmarshaler).
  4. Built-in parsing for string, bool, signed and unsigned integers, time.Duration, floats, and url.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.

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
}