What is viper-go-setup?

A Go pattern that initializes Viper with file, environment, and flag bindings, using a typed Config struct and an InitConfig function as shown in the Skill.

How does it handle a missing config file?

If a cfgFile is not provided, it looks for config.yaml in the working directory or $HOME/.myapp and ignores the error if the file is not found, allowing env overrides to take effect.

How do I customize environment variable prefixes?

Use viper.SetEnvPrefix("MYAPP") (or your app name) to scope env vars like MYAPP_HOST; the snippet demonstrates this exact approach.

viper-go-setup

npx machina-cli add skill a5c-ai/babysitter/viper-go-setup --openclaw

Files (1)

SKILL.md

1.3 KB

Viper Go Setup

Set up Viper for Go configuration management.

Generated Patterns

package config

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

type Config struct {
    Server   ServerConfig   `mapstructure:"server"`
    Database DatabaseConfig `mapstructure:"database"`
}

type ServerConfig struct {
    Host string `mapstructure:"host"`
    Port int    `mapstructure:"port"`
}

func InitConfig(cfgFile string) (*Config, error) {
    if cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        viper.SetConfigName("config")
        viper.SetConfigType("yaml")
        viper.AddConfigPath(".")
        viper.AddConfigPath("$HOME/.myapp")
    }

    viper.AutomaticEnv()
    viper.SetEnvPrefix("MYAPP")

    if err := viper.ReadInConfig(); err != nil {
        if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
            return nil, err
        }
    }

    var cfg Config
    if err := viper.Unmarshal(&cfg); err != nil {
        return nil, err
    }
    return &cfg, nil
}

Target Processes

configuration-management-system
cli-application-bootstrap

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/cli-mcp-development/skills/viper-go-setup/SKILL.md

View on GitHub

Overview

Viper Go Setup provides a ready-to-use InitConfig pattern to load application configuration from a file or environment, binding to strongly-typed Go structs. It maps YAML/JSON keys to Go fields using mapstructure tags and supports env overrides with a prefix. This helps Go CLI apps manage settings in a predictable, testable way.

How This Skill Works

Define a Config struct with nested ServerConfig and DatabaseConfig using mapstructure tags. InitConfig(cfgFile) selects the source: a provided cfgFile or defaults to a YAML file named config with fallback search paths. It enables automatic environment variables with a prefix, reads the config if present, and unmarshals it into the Config instance for use by the app.

When to Use It

Building a Cobra-based CLI that needs a structured configuration surface mapped to Go types.
If you want environment overrides to take precedence over config file values via a prefix like MYAPP.
When deploying to multiple environments (dev/stage/prod) with different config files or env values.
You need a clean separation between config loading and business logic with explicit InitConfig for startup.
You want a typed configuration object (Config) that can be passed to components without global state.

Quick Start

Step 1: Define Config, ServerConfig, and DatabaseConfig with mapstructure tags, as shown in the snippet.
Step 2: Implement InitConfig(cfgFile string) to choose between a file or default config name and type, enable env vars, and unmarshal into cfg.
Step 3: At startup, call InitConfig(cfgFile) and use the returned cfg to configure your components.

Best Practices

Define Config, ServerConfig, and DatabaseConfig with mapstructure tags to ensure correct binding from YAML/JSON.
Provide sensible default config paths (. and $HOME/.myapp) and allow an explicit cfgFile to override.
Enable AutomaticEnv and SetEnvPrefix to allow environment variables to override config values.
Handle ConfigFileNotFoundError gracefully to support env overrides when the file is missing.
Return the loaded config (not a global singleton) and pass it through to components for testability.

Example Use Cases

A server app reads host and port from config and database connection details, with env overrides via MYAPP_ prefix.
A CLI bootstrap that wires InitConfig with a config file path provided by a flag and uses the resulting cfg for setup.
An app with a config.yaml in the repo and environment-specific overrides set at runtime.
A microservice that searches ~/.myapp for a default config when no cfgFile is given and allows env vars to override.
An app that unmarshals config into a Config object and passes it to all subsystems (server, database, cache) without globals.

Frequently Asked Questions

Add this skill to your agents