intent

use spf13/viper to build layered configuration systems in go. viper resolves config keys by walking a fixed precedence pipeline: explicit Set() calls beat flags beat env vars beat config files beat remote KV beat defaults. apply this skill when adopting viper, integrating it with cobra CLI commands, or debugging why a config value isn't what you expect. viper has no user-facing surface , it's purely a key-value resolver that powers config-driven CLIs, daemons, and services.

inputs

• golang runtime: go 1.16+ (viper requires modern go)
• github.com/spf13/viper: installed via go get github.com/spf13/viper@latest
• config file (optional): yaml, toml, json, hcl, ini, or properties format at a path you control
• environment variables (optional): custom env vars with an optional prefix (e.g., MYAPP_PORT, MYAPP_DATABASE_HOST)
• command-line flags (optional): pflag.Flag instances from cobra or spf13/pflag to bind to viper keys
• remote KV (optional): etcd or consul endpoint for remote config (requires additional setup, see sources-and-formats.md)
• cobra (optional): only if you're building a multi-command CLI that needs both flags and config files

no external APIs or OAuth required. all inputs are local files, env vars, or in-process flag objects.

procedure

step 1: initialize viper and set defaults

input: a map of key-value pairs you want as fallback values output: viper instance ready to receive higher-priority sources

import "github.com/spf13/viper"

v := viper.New() // use viper.New() for isolation; avoid global viper in production
v.SetDefault("port", 8080)
v.SetDefault("database.host", "localhost")
v.SetDefault("database.max_conn", 10)

defaults are the lowest priority. always set them so missing config never causes a panic on a key lookup.

step 2: add a config file source (optional but common)

input: config file path, format (yaml/toml/json), and graceful-not-found handling output: config file values merged into viper, or skipped if file doesn't exist

v.SetConfigName("config")
v.AddConfigPath("$HOME/.myapp")
v.AddConfigPath("/etc/myapp")
v.SetConfigType("yaml")

if err := v.ReadInConfig(); err != nil {
    var notFound *viper.ConfigFileNotFoundError
    if !errors.As(err, &notFound) {
        return fmt.Errorf("reading config: %w", err)
    }
    // file not found is ok ,  we'll use flags/env/defaults instead
}

always handle ConfigFileNotFoundError separately. a missing config file should not crash a service that runs on flags and env vars alone.

step 3: wire env var resolution (if using env vars)

input: optional env var prefix (string), key replacer (for dots-to-underscores), and AutomaticEnv flag output: all three env settings bound together so nested keys like database.host resolve to MYAPP_DATABASE_HOST

v.SetEnvPrefix("MYAPP")                             // PORT → MYAPP_PORT
v.SetEnvKeyReplacer(strings.NewReplacer(".", "_")) // database.host → MYAPP_DATABASE_HOST
v.AutomaticEnv()                                    // read any env var matching the bound keys

critical: all three must be wired together at initialization time. missing SetEnvKeyReplacer causes dots to stay as dots in the env key lookup, so database.host looks for MYAPP_DATABASE.HOST (which doesn't exist on most systems) instead of MYAPP_DATABASE_HOST.

step 4: bind flags to viper keys (if using cobra or pflag)

input: a pflag.FlagSet (usually from cobra Command.Flags() or Command.PersistentFlags()), and a viper instance output: each flag value synced into viper so viper.Get("key") returns the flag value if set

import (
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)

var rootCmd = &cobra.Command{
    Use:  "myapp",
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        return viper.BindPFlags(cmd.PersistentFlags())
    },
}

func init() {
    rootCmd.PersistentFlags().Int("port", 8080, "listen port")
    rootCmd.PersistentFlags().String("database-host", "localhost", "db host")
    // bindings happen in PersistentPreRunE, which runs before any RunE
}

bind flags in PersistentPreRunE, not in RunE. cobra runs PersistentPreRunE before RunE, so bindings set in RunE are missed. flag names like database-host are automatically converted to database.host by viper.

alternatively, bind a single flag:

viper.BindPFlag("port", cmd.Flags().Lookup("port"))

step 5: read a config value

input: a key name (string), and the expected type (int, string, etc.) output: the resolved value from the highest-priority source, or the default if no source set it

port := v.GetInt("port")
dbHost := v.GetString("database.host")
dbMaxConn := v.GetInt("database.max_conn")

viper walks the precedence pipeline and returns the first value it finds. if no source set the key, it returns the default.

step 6: unmarshal into a struct (recommended for complex configs)

input: a pointer to a struct with mapstructure tags, a viper instance output: all resolved config values written into the struct fields

type Config struct {
    Port     int `mapstructure:"port"`
    Database struct {
        Host   string `mapstructure:"host"`
        MaxConn int `mapstructure:"max_conn"`
    } `mapstructure:"database"`
}

var cfg Config
if err := v.Unmarshal(&cfg); err != nil {
    return fmt.Errorf("unmarshaling config: %w", err)
}

always use explicit mapstructure tags on every field. implicit field mapping is fragile for nested structs and underscore-named keys.

alternatively, unmarshal a single subtree:

var dbCfg struct {
    Host   string `mapstructure:"host"`
    MaxConn int `mapstructure:"max_conn"`
}
if err := v.UnmarshalKey("database", &dbCfg); err != nil {
    return fmt.Errorf("unmarshaling database config: %w", err)
}

prefer UnmarshalKey over Sub + Unmarshal because Sub returns nil if the key doesn't exist (requiring an extra nil-check), while UnmarshalKey handles that gracefully.

step 7: watch and reload config (optional, for long-running services)

input: a viper instance with a config file, and a callback function output: the callback fires whenever the config file changes on disk

v.WatchConfig()
v.OnConfigChange(func(e fsnotify.Event) {
    fmt.Println("config changed, reloading...")
    var cfg Config
    if err := v.Unmarshal(&cfg); err != nil {
        fmt.Fprintf(os.Stderr, "reload failed: %v\n", err)
        return
    }
    applyNewConfig(cfg)
})

WatchConfig uses fsnotify to watch file inodes. caveat: editors like vim and neovim that write via atomic rename (write-to-temp, then rename) replace the inode, so the callback may not fire. test hot-reload with echo >> config.yaml (append), not editor saves.

decision points

if the config file is optional (most cases): use errors.As(err, &viper.ConfigFileNotFoundError) to distinguish "file not found" from "file found but unparseable". only return an error if the file was found but invalid. if the file is missing, proceed with env vars, flags, and defaults.

if you need nested config sub-trees: prefer UnmarshalKey("database", &dbCfg) over Sub("database").Unmarshal(&dbCfg). Sub returns nil if the key doesn't exist, forcing a nil-check; UnmarshalKey avoids that risk.

if using cobra (CLI with subcommands): bind flags in PersistentPreRunE, not in init() or RunE. cobra parses flags before PersistentPreRunE runs, so bindings set in PersistentPreRunE are available for config resolution. bindings set in RunE are too late because PersistentPreRunE already ran.

if the env key contains nested dots (e.g., database.host): always call SetEnvKeyReplacer(strings.NewReplacer(".", "_")) before AutomaticEnv(). without it, viper looks for DATABASE.HOST (dot preserved) instead of DATABASE_HOST, which doesn't exist on most systems.

if running tests: use viper.New() per test case, never the global viper instance. the global accumulates state across test runs, causing flaky ordering and cross-test contamination. each test should have its own isolated viper instance.

if the config key might not exist in any source: always check with viper.IsSet("key") before calling Get() methods. alternatively, use the default value set in step 1 to guarantee a sensible fallback.

output contract

on successful execution, the skill produces:

• a populated config struct or map containing all resolved values from the precedence pipeline (flag > env > file > KV > default). example:

  type Config struct {
      Port     int
      Database struct {
          Host   string
          MaxConn int
      }
  }
  

  with fields populated from the highest-priority source for each key.

• no errors from config loading, parsing, or unmarshaling (unless the config file is invalid, in which case the error is explicit and the caller can decide how to handle it).

• all viper methods callable on the instance without panics (e.g., Get(), GetInt(), GetString(), IsSet(), etc.).

the output is in-memory. viper does not write to files or external services (unless you explicitly call viper.WriteConfig() or similar, which is rare).

outcome signal

you know the skill worked when:

• viper.Get() and typed accessors (GetInt, GetString, etc.) return the expected values without panics or unexpected defaults. test with: fmt.Println(v.GetString("database.host")) , you should see the value from the highest-priority source (flag, then env, then file, then default).

• flags override env vars, and env vars override config files, in the correct order. test by setting the same key in a file, env var, and flag, then verify viper returns the flag value (highest priority). remove the flag and verify it returns the env var. remove the env var and verify it returns the file value.

• env vars with dots in the key name resolve correctly (e.g., setting MYAPP_DATABASE_HOST=localhost is read as database.host). test with: os.Setenv("MYAPP_DATABASE_HOST", "myhost"); v.SetEnvPrefix("MYAPP"); v.SetEnvKeyReplacer(strings.NewReplacer(".", "_")); v.AutomaticEnv(); fmt.Println(v.GetString("database.host")) , should print "myhost".

• config file parsing doesn't crash if the file is missing, and the program runs with env vars or defaults instead. test by removing the config file and confirming the service or CLI still starts.

• unmarshaling into a struct populates all fields, including nested ones, without silent misses. test with: var cfg Config; v.Unmarshal(&cfg); fmt.Printf("%+v\n", cfg) , all fields should be populated.

• hot-reload callbacks fire when the config file changes (for long-running services). test with: v.WatchConfig(); v.OnConfigChange(func(e fsnotify.Event) { fmt.Println("changed") }); echo "new_key: value" >> config.yaml , the callback should print "changed".

• each test case has isolated viper state (for unit tests). test by creating two test functions that each call viper.New(), setting different values, and confirming they don't interfere.