samber/cc-skills-golang / skills/golang-spf13-viper
golang-spf13-viper
VerifiedGolang 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 alongside viper, see the `samber/cc-skills-golang@golang-spf13-cobra` skill. For general CLI architecture, see `samber/cc-skills-golang@golang-cli`.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
| evals/evals.json | config | 21.0 KB |
| references/binding-and-env.md | markdown | 4.2 KB |
| references/sources-and-formats.md | markdown | 3.7 KB |
| references/testing-and-isolation.md | markdown | 4.1 KB |
| references/unmarshal.md | markdown | 4.4 KB |
| references/watch-and-reload.md | markdown | 3.5 KB |
references/sources-and-formats.md
View on GitHub# Viper Config Sources and File Formats
## Table of Contents
- [Supported file formats](#supported-file-formats)
- [Config file search](#config-file-search)
- [Merging multiple config files](#merging-multiple-config-files)
- [Multiple config files via SetConfigFile](#multiple-config-files-via-setconfigfile)
- [Remote KV stores (etcd, Consul)](#remote-kv-stores-etcd-consul)
- [Embedding config with go:embed](#embedding-config-with-goembed)
## Supported file formats
Viper detects format from file extension. Supported extensions:
| Format | Extensions |
| ---------- | --------------- |
| YAML | `.yaml`, `.yml` |
| TOML | `.toml` |
| JSON | `.json` |
| HCL | `.hcl` |
| INI | `.ini` |
| Properties | `.properties` |
| dotenv | `.env` |
Force a format when there is no extension:
```go
viper.SetConfigType("yaml")
viper.SetConfigFile("/etc/myapp/config") // no extension — type required
```
## Config file search
```go
viper.SetConfigName("config") // file name without extension
viper.SetConfigType("yaml") // required when no extension
viper.AddConfigPath("$HOME/.myapp") // search path 1 (highest priority when multiple)
viper.AddConfigPath("/etc/myapp/") // search path 2
viper.AddConfigPath(".") // search path 3 (lowest priority)
// viper searches paths in order, stops at the first match
if err := viper.ReadInConfig(); err != nil {
var notFound *viper.ConfigFileNotFoundError
if !errors.As(err, ¬Found) {
return err // real error (permission denied, malformed YAML, etc.)
}
// not found — continue with flags/env/defaults
}
// After reading, this returns the resolved path:
fmt.Println("Using config:", viper.ConfigFileUsed())
```
## Merging multiple config files
`MergeInConfig` merges a second config file into the current state. Later values override earlier ones for the same key.
```go
viper.SetConfigFile("base.yaml")
viper.ReadInConfig()
viper.SetConfigFile("override.yaml")
viper.MergeInConfig() // keys from override.yaml win on collision
```
Pattern: ship a base config with the binary, let users drop an override in `~/.myapp/override.yaml`.
## Multiple config files via SetConfigFile
For environment-based config loading:
```go
env := os.Getenv("APP_ENV")
if env == "" {
env = "development"
}
viper.SetConfigFile(fmt.Sprintf("config.%s.yaml", env))
viper.ReadInConfig()
```
## Remote KV stores (etcd, Consul)
Viper supports remote KV stores via the `viper/remote` sub-package. This keeps remote config behind an opt-in import:
```go
import _ "github.com/spf13/viper/remote"
// etcd
viper.AddRemoteProvider("etcd3", "http://127.0.0.1:2379", "/config/myapp.yaml")
viper.SetConfigType("yaml")
viper.ReadRemoteConfig()
// Consul
viper.AddRemoteProvider("consul", "localhost:8500", "myapp/config")
viper.SetConfigType("json")
viper.ReadRemoteConfig()
```
**Caution:** Remote config adds network latency to startup and a runtime dependency. Use it only when you need centralized config across many service instances. For most applications, files + env vars are sufficient.
Watch for remote changes:
```go
go func() {
for {
time.Sleep(5 * time.Second)
viper.WatchRemoteConfig()
// re-read values after watching
}
}()
```
## Embedding config with go:embed
Load config from embedded assets (for self-contained binaries):
```go
//go:embed config.yaml
var defaultConfig []byte
func init() {
viper.SetConfigType("yaml")
viper.ReadConfig(bytes.NewReader(defaultConfig))
}
```
`ReadConfig` accepts any `io.Reader`. This is useful for shipping default config inside the binary, then layering user overrides on top via `MergeInConfig`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |