golang-spf13-viper

Golang configuration library using spf13/viper — layered precedence (flag > env > file > KV > default), BindPFlag/BindPFlags, SetEnvPrefix + SetEnvKeyReplacer + AutomaticEnv, ReadInConfig + ConfigFileNotFoundError, Unmarshal + mapstructure struct tags, Sub for sub-trees, WatchConfig + OnConfigChange for hot reload, viper.New() for test isolation, and remote KV integration. Apply when using or adopting spf13/viper, or when the codebase imports `github.com/spf13/viper`. For CLI command structure a

2,201stars139forksUpdated 6/18/2026

Developer Tools #viper #configuration #config-management #golang #cli #environment-variables

Security Assessment

Safe(90/100)

Detected risks:

Sensitive File Access([references/sources-and-formats.md] .env)

Security Score90/100

About golang-spf13-viper

The golang-spf13-viper skill provides expert guidance for using spf13/viper, a powerful configuration management library for Go applications. Viper solves the common problem of managing configuration from multiple sources by implementing a layered precedence system where flags override environment variables, which override config files, which override key-value stores, which override defaults. This eliminates the need for custom configuration resolution logic and ensures consistent behavior across different deployment environments.

The skill covers viper's core capabilities including binding command-line flags (BindPFlag/BindPFlags), environment variable handling with prefix and key replacement (SetEnvPrefix, SetEnvKeyReplacer, AutomaticEnv), config file reading with proper error handling (ReadInConfig, ConfigFileNotFoundError), struct unmarshaling with mapstructure tags, configuration sub-trees (Sub), and hot-reload functionality (WatchConfig, OnConfigChange). It also addresses integration with cobra for CLI applications and remote key-value store support for distributed configuration.

This skill is designed for Go developers building applications that require flexible configuration management, particularly CLI tools, microservices, and daemons that need to support multiple configuration sources. It's especially valuable when adopting viper in existing projects or when working with codebases that import github.com/spf13/viper. The skill emphasizes understanding viper's fixed precedence pipeline to avoid common bugs like shadowed configuration values, and provides patterns for test isolation using viper.New().

FAQ

When should I use viper versus just using cobra flags?

Use cobra alone for simple flag-only CLIs. Use viper when you need configuration from multiple sources like config files, environment variables, and remote key-value stores. Viper and cobra work together: cobra owns the command structure and flags, while viper resolves configuration values from all sources with proper precedence.

How do I handle missing config files without crashing my application?

Check for ConfigFileNotFoundError specifically using errors.As() when ReadInConfig() returns an error. Missing config files should be handled gracefully since applications often run validly with only flags or environment variables. Only propagate non-ConfigFileNotFoundError errors.

Why isn't my config file value being used?

Viper uses a fixed precedence order: explicit Set() > flags > env vars > config files > remote KV > defaults. Your config file value may be shadowed by a higher-priority source like an environment variable or a flag with a default value. Check all sources in the precedence pipeline.

What are the requirements for using this skill?

This skill requires Go installed in your environment and is designed for projects using github.com/spf13/viper. It's compatible with Claude Code or similar AI coding agents. For CLI applications, it often pairs with the golang-spf13-cobra skill.

Does viper support hot-reloading configuration changes?

Yes, viper supports hot-reload through WatchConfig and OnConfigChange callbacks, allowing your application to react to configuration file changes without restarting.