skills.rest
VerifiedOrganic
VerifiedOrganicCOMMUNITY
Explore all skills by this author →
GitHub

golang-spf13-viper

Configures layered Go application settings with spf13/viper across flags, env vars, and files.

1|Updated Jun 2, 2026
Search Tags:#configuration#go#env vars#viper#cobra#hot reload#mapstructure
One-click install
npx skills add https://github.com/VerifiedOrganic/onboard --skill golang-spf13-viper-verifiedorganic
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-spf13-viper
Source: https://github.com/VerifiedOrganic/onboard/tree/main/.agents/skills/golang-spf13-viper
Command: npx skills add https://github.com/VerifiedOrganic/onboard --skill golang-spf13-viper-verifiedorganic

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Go services often misbehave because configuration values come from flags, environment variables, and files with unclear precedence, causing silent misreads, test pollution, and hot-reload races. This Skill encodes the correct spf13/viper patterns so an agent can diagnose and fix these issues directly. ## Core Features & Use Cases - Layered precedence and binding: Explains the fixed precedence pipeline (Set > flag > env > file > KV > default) and the required trio of SetEnvPrefix, SetEnvKeyReplacer, and AutomaticEnv for nested keys. - Struct unmarshaling and sub-trees: Covers Unmarshal with mapstructure tags, UnmarshalKey versus Sub nil risks, and DecodeHooks for time.Duration and custom types. - Hot reload and test isolation: Details WatchConfig fsnotify atomic-rename traps, race-safe OnConfigChange patterns, and viper.New() per-test isolation. - Use Case: A service panics on viper.Sub("database") when the key is missing, or env var MYAPP_DATABASE_HOST never resolves — the Skill pinpoints the nil-check and SetEnvKeyReplacer fixes. ## Quick Start Ask the agent to review or fix the viper configuration setup in your Go project, for example diagnosing why an environment variable is not overriding a config file value.

Frequently Asked Questions about golang-spf13-viper

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I bind environment variables to nested viper keys in Go?▼

Call SetEnvPrefix, SetEnvKeyReplacer(strings.NewReplacer(".", "_")), and AutomaticEnv together before reading values. Without the key replacer, viper looks up MYAPP_DATABASE.HOST with the dot preserved, so nested keys like database.host never resolve.

Why does viper.Sub return nil and panic in my Go service?▼

viper.Sub returns nil when the key does not exist, and calling Unmarshal on nil panics. Add a nil check before use, or prefer viper.UnmarshalKey("database", &dbCfg), which avoids the nil risk entirely.

Can I use viper without cobra for a non-CLI Go service?▼

Yes, viper works standalone for HTTP services and daemons that only need config files and environment variables. Cobra is only needed when you want a command tree with flags bound via BindPFlag.

Why does viper.Unmarshal leave my time.Duration field at zero?▼

mapstructure cannot decode a duration string like "30s" into time.Duration by default. Register mapstructure.StringToTimeDurationHookFunc() through a DecodeHook option passed to viper.Unmarshal.

Why does viper WatchConfig not fire when I save in vim?▼

Vim and many editors write atomically via rename, which replaces the inode fsnotify is watching, so the callback may not fire. Test hot reload with direct writes like os.WriteFile instead of editor saves.

How do I isolate viper state between Go tests?▼

Create a fresh viper.New() instance per test instead of using the global viper, whose state leaks across tests and causes order-dependent failures. Combine with t.Setenv for environment variable tests.

Related Skills

Explore More Software Engineering Skills→
QunnnnQunnnn

go-spf13-viper

Manage layered configuration loading and precedence with spf13/viper in Go.

Community
Intermediate
overviewlabsoverviewlabs

native-mcp

Connect to MCP servers and expose their tools as native WHOX tools.

Community
Advanced
28773895772877389577

golang-spf13-cobra

Build and test Go CLI command trees using the spf13/cobra library.

Community
Intermediate
ozan-fnozan-fn

golang-spf13-viper

Manage Golang application configurations with spf13/viper layered precedence and hot reload.

Community
Advanced