Skip to content

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

main.go
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:

YAML
import "github.com/conga-sh/conga/decoder/yaml"
app.RegisterDecoder(".yaml", yaml.Decode)
app.RegisterDecoder(".yml", yaml.Decode)

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:

main.go
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:

Terminal window
$ cascading-searchpaths --why
Value 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()

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":

main.go
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:

Terminal window
$ cascading-searchpaths --why
Value 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.yaml

The system file also sets timeout: 30s, but the user’s 15s wins. Flags on the command line and environment variables still beat every file.

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:

Terminal window
$ APP_CONFIG=nope.yaml cascading-searchpaths
Error:cascading-searchpaths: error: cannot read config file "nope.yaml": stat nope.yaml: no such file or directory

An env tag on the ConfigFile field names the variable instead of APP_CONFIG, and env:"-" gives the flag no variable:

main.go
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:

Terminal window
$ cascading-searchpaths -c team.yaml -c ci.yaml --why
Value 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 loaded

Without multi:"true", the flag takes one file and its help reads --config-file=PATH. A named file must exist:

Terminal window
$ cascading-searchpaths -c nope.yaml
Error:cascading-searchpaths: error: cannot read config file "nope.yaml": stat nope.yaml: no such file or directory

ConfigFile belongs on the root command, and subcommands read the loaded files through the session (see List the config files a run loaded).

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:

main.go
Token conga.OptionalFlag[string] `config:"-" help:"API token (command line or environment only)"`

A file that sets it is rejected:

Terminal window
$ cascading-searchpaths -c token.yaml
Error:cascading-searchpaths: error: config file "token.yaml": field "token" is excluded from config files in command "cascading-searchpaths"

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.

main.go
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:

snake.yaml
api_endpoint: https://api.example.com
timeout: 30s
Terminal window
$ cascading-searchpaths -c snake.yaml --why
Value 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 loaded

The kebab-case key is now unknown:

Terminal window
$ cascading-searchpaths -c kebab.yaml
Error:cascading-searchpaths: error: config file "kebab.yaml": unknown field "api-endpoint" in command "cascading-searchpaths" (did you mean "api_endpoint"?)

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:

main.go
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"`
}
server.yaml
api-endpoint: https://api.example.com
timeout: 30s
telemetry: false
server:
port: 9000
headers:
Cache-Control: no-store
X-Team: payments
Terminal window
$ cascading-searchpaths -c server.yaml server --why
Value 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) - telemetry
Config decoders: .yaml, .yml
Config paths:
server.yaml loaded

About subcommands and hierarchy describes how deeper hierarchies map.

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:

main.go
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:

main.go
app.RegisterDecoder(".ini", iniDecoder)

An error from the decoder names the file:

Terminal window
$ cascading-searchpaths -c bad.ini
Error:cascading-searchpaths: error: cannot parse config file "bad.ini": malformed line: "theme light"

For files that mix configuration with application data, such as a Taskfile, use a conga.Bootstrapper instead of a decoder.

session.CandidateConfigFiles() returns the places the program searched, and session.LoadedConfigFiles() the files it loaded, lowest precedence first:

main.go
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
}
Terminal window
$ cascading-searchpaths server
port=8080
candidates=["." "/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"]

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"?)
Error: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")