Stage 3 · Build

Building CLI Tools

Viper for Configuration

Env vars, config files, remote config, and pflag binding for layered configuration.

6 min readGo for SREBuild

Why Viper

Viper is the standard configuration library for Go CLI tools. It handles config files, environment variables, command-line flags, and remote key-value stores — all with a unified API.

Install Viper


go get github.com/spf13/viper@latest

Viper works well with Cobra. Bind Cobra flags directly to Viper keys and get automatic precedence: flag > env > config file > default.

Configuration Sources

Viper reads configuration from multiple sources with a clear precedence order. This lets operators customize behavior without changing code or command-line flags.

Gosetting-up-config-sources.go

22 linesLn 1, Col 1Go

Viper searches for config files in order. The first file found wins. ConfigFileNotFoundError is non-fatal — the app can run with defaults and env vars alone.

Environment Variable Overrides

Environment variables override config file values. This is essential for container deployments where config files are impractical.

Goenv-var-configuration.go

11 linesLn 1, Col 1Go

AutomaticEnv maps config keys to env vars using the prefix and key separator. SetEnvKeyReplacer lets you use dots in config keys and underscores in env vars. BindEnv maps specific keys to specific env vars.

Use 12-factor app conventions

Prefer environment variables for deployment-specific values (ports, hosts, credentials). Use config files for structural configuration (feature flags, thresholds, lists). This follows the 12-factor app methodology.

Config to Struct Binding

Bind configuration to Go structs for type safety and IDE autocompletion. Viper uses mapstructure tags to map config keys to struct fields.

Gostruct-binding.go

24 linesLn 1, Col 1Go

mapstructure tags define how config keys map to struct fields. viper.Unmarshal handles nested structs automatically. The returned config is fully validated and ready to use.

Live Reload

Viper can watch config files for changes. When the file is modified, Viper fires an event that your application can handle.

Goconfig-file-watching.go

15 linesLn 1, Col 1Go

WatchConfig starts a goroutine that monitors the config file. OnConfigChange fires when the file is modified. Always handle errors during reload — the new config may be invalid.

Sensible Defaults

Defaults make your tool work out of the box. Set reasonable defaults for every configuration option and document them in the help text.

Gocomprehensive-defaults.go

18 linesLn 1, Col 1Go

Set defaults before reading the config file. Defaults fill in any keys not present in the config file or env vars. Use types that match your struct fields — Viper handles type conversion.

Validate configuration after loading

Viper does not validate configuration values. Always validate after Unmarshal: check port ranges, required fields, and valid enum values. Return clear error messages for invalid configuration.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.