Skip to content

About value precedence

Configuration values in CONGA follow Twelve-Factor principles. Command-line arguments override environment variables, environment variables override config files, and config files override defaults. Resolution runs in two phases, one that finds the config files and one that binds values, and a few containers depart from the general order. How to bind environment variables and How to manage config files set the sources up.

A flag resolves through four sources, highest first:

1. CLI explicit --flag or -f on the command line
2. Environment $<PREFIX>_<FLAG> (via EnvPrefix or envprefix), or an explicit env tag
3. Config keys from loaded config files, or values from Bootstrap.SetConfig
4. Default the `default:"..."` struct tag

The first source that supplies a value wins. With no source, a flag holds its type’s zero value and reports SourceNone.

Resolution completes before any lifecycle hook runs, in two sequential phases:

Resolution runs in two phases. Phase 1 picks the config files. It tries the ConfigFile flag, then the config environment variable, then ConfigExplicit, then the search paths, and the first that applies wins. The files it loads form the config map. Phase 2 binds each flag from the command line, then the environment, then its key in the config map, then its default tag, and the first source that supplies a value wins. Phase 1: config file discovery first that applies wins ConfigFile flag --config-file by default Config variable <PREFIX>_CONFIG ConfigExplicit path set in code Search paths ConfigPaths or XDG Phase 2: flag value binding first that applies wins Command line --flag Environment <PREFIX>_<FLAG> Config file key in the config map Default default tag Loaded config map

Before binding any flag, CONGA determines which config files to load and decodes them into one key-value map. Discovery has its own precedence, with --config-file first, then <PREFIX>_CONFIG, then conga.ConfigExplicit(...), then the search paths. The paths a user names come before the ones the program sets, as values from the command line and environment come before config and defaults in Phase 2. About the config cascade covers the existence rules and merging. Once the files load and validate against the schema, their keys are the lookup table for Phase 2.

A conga.Bootstrapper runs before Phase 1 and can contribute a config document with Bootstrap.SetConfig. The document’s values join the config source, overlaying file values key by key.

With the config map loaded, CONGA evaluates the precedence order for each flag on the selected command chain. The winning source sets the container’s value and provenance. Map flags are the exception. Every source contributes its keys, and higher sources override per key (see Map flags).

Why ConfigFile sits outside the precedence order

Section titled “Why ConfigFile sits outside the precedence order”

conga.ConfigFile is declared like a flag on the root command, but it governs file discovery (Phase 1) rather than value binding (Phase 2).

A config file cannot name the config file to load, so the config source cannot feed itself.

For the same reason, schema build rejects a default tag on a ConfigFile field. A default path would be neither loaded nor validated by the config engine. Probed locations belong in search paths (conga.ConfigPaths), and an example path shown in help belongs in placeholder.

ConfigFile instead records Phase 1. It names the files that discovery loaded, whether from the command line, the environment, ConfigExplicit, or a search path. When no file loads, it stays unset (SourceNone).

Not every container reads all four sources.

RequiredFlag[T] has no fallback. If the command line, environment, and config files all leave it unset, resolution stops before the command runs with a usage error (exit code 2).

env:"-" and config:"-" remove a flag from the environment or config source, so only the remaining sources can set it.

CONGA skips the config search paths if an application does not register a config decoder, and values fall from the environment straight to defaults. A file named with --config-file or with the ConfigFile field’s environment variable still needs a decoder, and fails with ErrConfig (exit 1) without one. An app with neither a decoder nor a ConfigFile doesn’t read <PREFIX>_CONFIG, so one of its flags can bind that variable. A Bootstrapper can still supply the config source in code with Bootstrap.SetConfig.

RequiredArg[T], OptionalArg[T], DashArgs, and RawArgs read only command-line tokens. OptionalArg[T] falls back to its default tag.

Scalar and slice flags take the value of the single winning source. map[K]V flags, including registered map types, merge key by key across all four sources instead. Each source contributes key=value pairs, applied from lowest to highest, so a higher source overrides only the keys it names. Within the config source, cascading applies the same rule across files, and the nearest file wins each key.

Source, lowest first Contributed keys Map after this source
Default tag region=us-east-1, timeout=30s region=us-east-1, timeout=30s
Config file timeout=60s, retries=3 region=us-east-1, timeout=60s, retries=3
Environment retries=5, debug=true region=us-east-1, timeout=60s, retries=5, debug=true
Command line debug=false, profile=dev region=us-east-1, timeout=60s, retries=5, debug=false, profile=dev

This matches the convention of Kubernetes --feature-gates, Helm --set, and git -c. A higher source can change a key set by a lower one, but cannot remove it.

Because every source contributes, CONGA parses map entries from every active source, even when the command line also sets the flag. A malformed entry on the command line is a usage error: ErrCoerce, exit 2. A malformed entry in a config file or an environment variable comes from a lower source, so it classifies under ErrConfig with exit 1, even when the command line also sets the flag. The message names the origin, such as invalid key-value pair "novalue", expected KEY=VALUE for flag --labels (from environment variable TOOL_LABELS) or (from config key "labels").

A conga.Features[T] container resolves through the same key-by-key merge, then overlays its fields’ default tags, so features no source names keep their defaults. CONGA canonicalizes feature keys before merging, so precedence follows the source, never the spelling. The application’s EnvPrefix never applies to features. About feature toggles explains the merge and its environment variables.

With app.Dotenv(), variables from .env files enter the process environment before resolution and bind as ordinary environment variables (Dotenv files).

An empty variable (FOO=) counts as unset for every flag type, string flags included, so lower sources apply. To set a string flag to the empty string, pass --flag "" on the command line.

Every container records the source that won and the exact origin within it. For a value from the config source, the origin is the file path as resolved, or the label a bootstrap document recorded with Set, falling back to the config key when the document gives no label. A scalar or slice names its single winning file, and a merged map lists every contributing file in load order:

source := cmd.Addr.Source() // conga.SourceCLI, SourceEnv, SourceConfig, etc.
detail := cmd.Addr.SourceDetail() // "--addr", "CLOUDCTL_ADDR", "/etc/cloudctl/app.toml"
if cmd.Addr.Changed() {
// Value came from the command line, the environment, or a config file
}
Constant Meaning
conga.SourceCLI Bound from a command-line flag or argument token
conga.SourceEnv Resolved from an environment variable
conga.SourceConfig Read from a loaded config file or a bootstrap document
conga.SourceDefault Supplied by a default tag
conga.SourceNone Set by no source, holding the type’s zero value

Changed() reports whether the command line, the environment, or a config file supplied the value, separating explicitly configured values from defaults.

With app.EnableWhy(), the --why flag prints the winning source and origin of every flag on the selected command chain. The --why report documents the output, and How to inspect value provenance walks through a diagnosis.