How to manage config files
A config file gives flags their values when the user leaves them off the command line and no environment variable sets them. This guide registers a format, searches three places for a file, merges every file found, lets users name their own files, and maps fields to keys.
The running example is the cascading search paths example. Paths in the output use /home/alice as the home directory.
Register the formats you accept
Section titled “Register the formats you accept”Register a decoder for each file extension the application reads. Decoders are separate packages, so an application links only the formats it registers. The struct below also declares a conga.ConfigFile field, the container for the config-file flag. It gives users -c / --config-file and holds the paths they name (Let users name their own files):
package main
import ( "context" "time"
"github.com/conga-sh/conga" "github.com/conga-sh/conga/decoder/yaml")
type CLI struct { ConfigFile conga.ConfigFile `multi:"true" short:"c"`
APIEndpoint conga.OptionalFlag[string] `default:"https://api.default.io" safe:"true"` Timeout conga.OptionalFlag[time.Duration] `default:"10s" help:"Request timeout" safe:"true"` Theme conga.OptionalFlag[string] `default:"dark" enum:"dark,light,solarized,system" safe:"true"` Telemetry conga.OptionalFlag[bool] `default:"true" help:"Enable telemetry reporting"`}
func (c *CLI) Run(ctx context.Context, session *conga.Session) error { return nil}
func main() { app := conga.New[CLI](). Name("cascading-searchpaths"). EnableWhy(). RegisterDecoder(".yaml", yaml.Decode). RegisterDecoder(".yml", yaml.Decode)
if err := app.Run(); err != nil { app.Exit(err) }}Users see the accepted formats on the config flag in --help:
-c, --config-file=PATH,... Path to config file(s) [decoders: .yaml, .yml]CONGA ships decoders for JSON, TOML, YAML, and HCL in conga/decoder/... (package decoder).
To accept another format, import its decoder package and register its extension:
import "github.com/conga-sh/conga/decoder/yaml"
app.RegisterDecoder(".yaml", yaml.Decode)app.RegisterDecoder(".yml", yaml.Decode)import "github.com/conga-sh/conga/decoder/toml"
app.RegisterDecoder(".toml", toml.Decode)import "github.com/conga-sh/conga/decoder/json"
app.RegisterDecoder(".json", json.Decode)import "github.com/conga-sh/conga/decoder/hcl"
app.RegisterDecoder(".hcl", hcl.Decode)Search for a file in several places
Section titled “Search for a file in several places”Add ConfigPaths with the places to look, highest precedence first. For an entry that is an existing directory, the program looks there for config.<ext> and <app-name>.<ext> for every registered extension. An existing file is used as it is. An entry that does not exist is tried as <entry>.<ext>, so without a ~/.config/cascading-searchpaths directory, the program looks for ~/.config/cascading-searchpaths.yaml. ~ and ${VAR:-default} expand:
app := conga.New[CLI](). Name("cascading-searchpaths"). EnableWhy(). RegisterDecoder(".yaml", yaml.Decode). RegisterDecoder(".yml", yaml.Decode). ConfigOptions(conga.ConfigPaths(".", "~/.config/cascading-searchpaths", "${SYSCONF_DIR:-/etc/cascading-searchpaths}"))The program loads the first file it finds and stops. In this run, all three places have a file:
Directory./ working directory
- cascading-searchpaths.yaml loaded
Directory~/.config/cascading-searchpaths/
- cascading-searchpaths.yaml
Directory/etc/cascading-searchpaths/
- cascading-searchpaths.yaml
The one in the working directory wins:
$ cascading-searchpaths --whyValue provenance for "cascading-searchpaths":
FLAG VALUE SOURCE ENV CONFIG PATH --config-file cascading-searchpaths.yaml config - - --api-endpoint https://api.local.dev config (cascading-searchpaths.yaml) - api-endpoint --timeout 10s default - timeout --theme dark default - theme --telemetry true default - telemetry
Config decoders: .yaml, .yml
Config paths: . loaded: cascading-searchpaths.yaml /home/alice/.config/cascading-searchpaths skipped (an earlier location loaded) /etc/cascading-searchpaths skipped (an earlier location loaded)Without ConfigPaths, the program looks in the user’s config directory, ${XDG_CONFIG_HOME:-~/.config}, and About the config cascade covers that default. To load one fixed file instead of searching, use conga.ConfigExplicit(path). The run then fails if that file is missing. ConfigExplicit takes the place of the search, so a program that also passes ConfigPaths or ConfigCascading fails at startup:
Error:cascading-searchpaths: error: schema error: conga.ConfigExplicit() names a single configuration file and cannot be combined with conga.ConfigPaths() or conga.ConfigCascading()ErrorMerge files from every place
Section titled “Merge files from every place”Add ConfigCascading() to load every file found and merge them key by key, higher places winning. The ConfigFile flag must then accept several files, with multi:"true" as in the struct above, or the program fails at startup with schema error: conga.ConfigCascading() merges multiple config files; the root config-file flag "config-file" must declare multi:"true":
ConfigOptions( conga.ConfigPaths(".", "~/.config/cascading-searchpaths", "${SYSCONF_DIR:-/etc/cascading-searchpaths}"), conga.ConfigCascading(),)Each value now comes from the highest file that sets it. Here the working directory sets api-endpoint, the user’s file sets theme and timeout, and the system file sets telemetry:
$ cascading-searchpaths --whyValue provenance for "cascading-searchpaths":
FLAG VALUE SOURCE ENV CONFIG PATH --config-file (3 files) config - - ├─ /etc/cascading-searchpaths/cascading-searchpaths.yaml ├─ /home/alice/.config/cascading-searchpaths/cascading-searchpaths.yaml └─ cascading-searchpaths.yaml --api-endpoint https://api.local.dev config (cascading-searchpaths.yaml) - api-endpoint --timeout 15s config (/home/.../cascading-searchpaths.yaml) - timeout --theme light config (/home/.../cascading-searchpaths.yaml) - theme --telemetry false config (/etc/.../cascading-searchpaths.yaml) - telemetry
Config decoders: .yaml, .yml
Config paths: . loaded: cascading-searchpaths.yaml /home/alice/.config/cascading-searchpaths loaded: /home/alice/.config/cascading-searchpaths/cascading-searchpaths.yaml /etc/cascading-searchpaths loaded: /etc/cascading-searchpaths/cascading-searchpaths.yamlThe system file also sets timeout: 30s, but the user’s 15s wins. Flags on the command line and environment variables still beat every file.
Let users name their own files
Section titled “Let users name their own files”The ConfigFile field gives users -c / --config-file. Naming a file replaces the search, and the program loads only the named files.
With an EnvPrefix, the flag also reads a variable. Here EnvPrefix("APP") was added, and help lists APP_CONFIG under the flag:
-c, --config-file=PATH,... Path to config file(s) [decoders: .yaml, .yml] [env: APP_CONFIG]A file named in APP_CONFIG must exist, as with -c:
$ APP_CONFIG=nope.yaml cascading-searchpathsError:cascading-searchpaths: error: cannot read config file "nope.yaml": stat nope.yaml: no such file or directoryErrorAn env tag on the ConfigFile field names the variable instead of APP_CONFIG, and env:"-" gives the flag no variable:
ConfigFile conga.ConfigFile `env:"CASCADE_CONFIG" multi:"true" short:"c"` -c, --config-file=PATH,... Path to config file(s) [decoders: .yaml, .yml] [env: CASCADE_CONFIG]The program now ignores APP_CONFIG. Schema build rejects a flag or feature bound to the config file’s variable, as Rename a flag that reads the config file’s variable shows.
With multi:"true", users can repeat -c, and a later file beats an earlier one:
$ cascading-searchpaths -c team.yaml -c ci.yaml --whyValue provenance for "cascading-searchpaths":
FLAG VALUE SOURCE ENV CONFIG PATH --config-file (2 files) cli - - ├─ team.yaml └─ ci.yaml --api-endpoint https://api.default.io default - api-endpoint --timeout 5s config (ci.yaml) - timeout --theme solarized config (team.yaml) - theme --telemetry true default - telemetry
Config decoders: .yaml, .yml
Config paths: team.yaml loaded ci.yaml loadedWithout multi:"true", the flag takes one file and its help reads --config-file=PATH. A named file must exist:
$ cascading-searchpaths -c nope.yamlError:cascading-searchpaths: error: cannot read config file "nope.yaml": stat nope.yaml: no such file or directoryErrorConfigFile belongs on the root command, and subcommands read the loaded files through the session (see List the config files a run loaded).
Match keys to fields
Section titled “Match keys to fields”A key is the flag’s name, written exactly, so --api-endpoint reads api-endpoint: (to use snake_case or camelCase keys, see Choose the key casing). Other spellings and letter cases, such as api_endpoint: or API-Endpoint:, are unknown keys, and so are the flag’s aliases. The CONFIG PATH column of --why shows each flag’s key.
To read a different key, set config:"<key>". The flag then reads that key and no longer reads its name. To keep a field out of config files, set config:"-". This variation adds a token that users pass on the command line or in the environment only:
Token conga.OptionalFlag[string] `config:"-" help:"API token (command line or environment only)"`A file that sets it is rejected:
$ cascading-searchpaths -c token.yamlError:cascading-searchpaths: error: config file "token.yaml": field "token" is excluded from config files in command "cascading-searchpaths"ErrorChoose the key casing
Section titled “Choose the key casing”Keys derived from names follow one casing for the whole app, kebab-case by default. Add conga.ConfigKeyCase to ConfigOptions to use conga.SnakeCase or conga.CamelCase instead. The casing changes only how config files spell the keys: under SnakeCase, the flag --api-endpoint still has that name on the command line, and its config key becomes api_endpoint. Subcommand section names and feature names in the features section follow the same casing. A config:"<key>" tag is always read as written.
ConfigOptions( conga.ConfigPaths(".", "~/.config/cascading-searchpaths", "${SYSCONF_DIR:-/etc/cascading-searchpaths}"), conga.ConfigCascading(), conga.ConfigKeyCase(conga.SnakeCase),)--api-endpoint now reads api_endpoint:, and --why shows the new key:
api_endpoint: https://api.example.comtimeout: 30s$ cascading-searchpaths -c snake.yaml --whyValue provenance for "cascading-searchpaths":
FLAG VALUE SOURCE ENV CONFIG PATH --config-file snake.yaml cli - - --api-endpoint https://api.example.com config (snake.yaml) - api_endpoint --timeout 30s config (snake.yaml) - timeout --theme dark default - theme --telemetry true default - telemetry
Config decoders: .yaml, .yml
Config paths: snake.yaml loadedThe kebab-case key is now unknown:
$ cascading-searchpaths -c kebab.yamlError:cascading-searchpaths: error: config file "kebab.yaml": unknown field "api-endpoint" in command "cascading-searchpaths" (did you mean "api_endpoint"?)ErrorNest subcommand settings
Section titled “Nest subcommand settings”A subcommand’s flags live under a section named after the subcommand, and root flags stay at the top level of the file. This variation adds a server subcommand with a port and a map of response headers:
type CLI struct { // ... Server conga.Command[ServerCmd] `summary:"Run the API server"`}
type ServerCmd struct { Port conga.OptionalFlag[int] `default:"8080" safe:"true" help:"Listen port"` Headers conga.OptionalFlag[map[string]string] `safe:"true" help:"Headers added to every response"`}api-endpoint: https://api.example.comtimeout: 30stelemetry: false
server: port: 9000 headers: Cache-Control: no-store X-Team: paymentsapi-endpoint = "https://api.example.com"timeout = "30s"telemetry = false
[server]port = 9000
[server.headers]Cache-Control = "no-store"X-Team = "payments"{ "api-endpoint": "https://api.example.com", "timeout": "30s", "telemetry": false, "server": { "port": 9000, "headers": { "Cache-Control": "no-store", "X-Team": "payments" } }}api-endpoint = "https://api.example.com"timeout = "30s"telemetry = false
server { port = 9000 headers = { "Cache-Control" = "no-store" "X-Team" = "payments" }}$ cascading-searchpaths -c server.yaml server --whyValue provenance for "cascading-searchpaths server":
FLAG VALUE SOURCE ENV CONFIG PATH --port 9000 config (server.yaml) - server.port --headers (2 keys) config (server.yaml) - server.headers ├─ Cache-Control=no-store config (server.yaml) └─ X-Team=payments config (server.yaml)
Global Flags:
FLAG VALUE SOURCE ENV CONFIG PATH --config-file server.yaml cli - - --api-endpoint https://api.example.com config (server.yaml) - api-endpoint --timeout 30s config (server.yaml) - timeout --theme dark default - theme --telemetry false config (server.yaml) - telemetryAbout subcommands and hierarchy describes how deeper hierarchies map.
Add a format of your own
Section titled “Add a format of your own”A decoder is a function with the signature func(data []byte) (map[string]any, error) that turns the file into a map of keys to values, with nested maps for subcommand sections. This one reads key = value lines:
func iniDecoder(data []byte) (map[string]any, error) { result := make(map[string]any) scanner := bufio.NewScanner(bytes.NewReader(data))
for scanner.Scan() { line := strings.TrimSpace(scanner.Text()) if line == "" || strings.HasPrefix(line, "#") || strings.HasPrefix(line, ";") { continue }
key, value, found := strings.Cut(line, "=") if !found { return nil, fmt.Errorf("malformed line: %q", line) }
result[strings.TrimSpace(key)] = strings.TrimSpace(value) }
if err := scanner.Err(); err != nil { return nil, err }
return result, nil}Register it like a built-in decoder, and .ini joins the formats listed in --help:
app.RegisterDecoder(".ini", iniDecoder)An error from the decoder names the file:
$ cascading-searchpaths -c bad.iniError:cascading-searchpaths: error: cannot parse config file "bad.ini": malformed line: "theme light"ErrorFor files that mix configuration with application data, such as a Taskfile, use a conga.Bootstrapper instead of a decoder.
List the config files a run loaded
Section titled “List the config files a run loaded”session.CandidateConfigFiles() returns the places the program searched, and session.LoadedConfigFiles() the files it loaded, lowest precedence first:
func (s *ServerCmd) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "port=%d\n", s.Port.Get()) fmt.Fprintf(session.Stdout(), "candidates=%q\n", session.CandidateConfigFiles()) fmt.Fprintf(session.Stdout(), "loaded=%q\n", session.LoadedConfigFiles())
return nil}$ cascading-searchpaths serverport=8080candidates=["." "/home/alice/.config/cascading-searchpaths" "/etc/cascading-searchpaths"]loaded=["/etc/cascading-searchpaths/cascading-searchpaths.yaml" "/home/alice/.config/cascading-searchpaths/cascading-searchpaths.yaml" "cascading-searchpaths.yaml"]Know what users see when a file is wrong
Section titled “Know what users see when a file is wrong”A problem with the file itself, or with a value it supplies, is a config error (exit 1). That includes a valid file whose value fails to coerce or validate: the value did not come from the command line, so the failure classifies under ErrConfig and names the key it came from. Only command-line values are usage errors (exit 2):
| What the file has | Result |
|---|---|
A -c file that doesn’t exist |
Config error, exit 1 |
| Text the decoder can’t parse | Config error, exit 1, naming the file |
| An extension with no registered decoder | Config error, exit 1 |
An unknown key (them: dark) |
Config error, exit 1, with a “did you mean” hint |
A key in another spelling (api_endpoint: for --api-endpoint) |
Config error, exit 1, with a “did you mean” hint |
A key for a config:"-" field |
Config error, exit 1 |
A value of the wrong type (timeout: soon) |
Config error, exit 1, naming the key |
A value outside enum or range (theme: pink) |
Config error, exit 1, naming the key |
Error:cascading-searchpaths: error: config file "typo.yaml": unknown field "them" in command "cascading-searchpaths" (did you mean "theme"?)ErrorError:cascading-searchpaths: error: config file "snake.yaml": unknown field "api_endpoint" in command "cascading-searchpaths" (did you mean "api-endpoint"?)Error:cascading-searchpaths: error: unsupported config file format ".toml" for "settings.toml"Error:cascading-searchpaths: error: invalid duration "soon" (valid units: ms, s, m, h) for flag --timeout (from config key "timeout")Error:cascading-searchpaths: error: invalid value "pink" (must be one of: dark, light, solarized, system) for flag --theme (from config key "theme")Where to go next
Section titled “Where to go next”- About the config cascade: search order, the XDG default, and how merging works.
- Package decoder: the JSON, TOML, YAML, and HCL decoders.
- How to load domain documents: files that mix configuration with application data.
- How to inspect value provenance: the full
--whyreport. - Cascading search paths example: the program used on this page.