Gookit Config

config - Configuration Management for Go

Simple, full-featured application configuration management tool library for Go.

Overview

gookit/config provides a unified API to manage configuration from multiple formats and sources. Load from files, environment variables, CLI flags, or remote URLs - all with automatic merging and type-safe access.

Key Features

📦 Multiple Formats

• JSON (default, with comments support)
• YAML - Popular for config files
• TOML - Simple and readable
• INI - Classic format
• Properties - Java-style
• JSON5 - JSON with extras
• HCL - HashiCorp config (via custom driver)
• ENV - Environment variables
• Flags - Command-line arguments

🔄 Multiple Sources

• Load from files (single or multiple)
• Load from OS environment variables
• Load from CLI flags
• Load from remote URLs
• Load from Go structs/maps
• Auto-merge multiple sources by key

🎯 Smart Features

• Key path access: config.String("db.host")
• ENV parsing: ${SHELL|/bin/bash} with defaults
• Struct binding: Map config to Go structs
• Default values: From struct tags or ENV
• Change events: Listen for config updates
• File watching: Auto-reload on file changes
• Type-safe API: Get, Int, String, Bool, etc.

Installation

go get github.com/gookit/config/v2

Quick Start

Basic Usage

package main

import (
    "github.com/gookit/config/v2"
    "github.com/gookit/config/v2/yaml"
)

func main() {
    // Enable ENV parsing
    config.WithOptions(config.ParseEnv)

    // Add YAML driver
    config.AddDriver(yaml.Driver)

    // Load config file
    err := config.LoadFiles("config.yaml")
    if err != nil {
        panic(err)
    }

    // Get values
    name := config.String("app.name")
    debug := config.Bool("app.debug")
    port := config.Int("server.port")
}

config.yaml:

app:
  name: myapp
  debug: true

server:
  host: 0.0.0.0
  port: 8080
  timeout: 30s

database:
  host: ${DB_HOST|localhost}
  port: ${DB_PORT|5432}
  username: ${DB_USER}

Load Multiple Files

// Files are auto-merged by key
config.LoadFiles("config.yaml", "config.prod.yaml")

// Or load separately
config.LoadFiles("config.yaml")
config.LoadFiles("config.prod.yaml") // Overrides values from first file

Get Configuration Values

// Simple values
name := config.String("app.name")
debug := config.Bool("app.debug")
port := config.Int("server.port")
timeout := config.Float("timeout")

// With defaults
host := config.String("server.host", "127.0.0.1")
port := config.Int("server.port", 8080)

// Arrays
tags := config.Strings("tags")           // []string
ports := config.Ints("ports")            // []int

// Maps
settings := config.StringMap("settings") // map[string]string
features := config.Get("features")       // interface{}

// Key path access
dbHost := config.String("database.host")
firstTag := config.String("tags.0")      // Access array by index

Bind to Struct

type Config struct {
    App struct {
        Name  string `mapstructure:"name"`
        Debug bool   `mapstructure:"debug"`
    } `mapstructure:"app"`

    Server struct {
        Host string `mapstructure:"host"`
        Port int    `mapstructure:"port"`
    } `mapstructure:"server"`
}

var cfg Config
err := config.Decode(&cfg)
// or bind specific key
err := config.BindStruct("app", &cfg.App)

fmt.Println(cfg.App.Name)   // "myapp"
fmt.Println(cfg.Server.Port) // 8080

Load from ENV

// OS ENV: APP_NAME=myapp APP_DEBUG=true DB_HOST=localhost

// Map ENV vars to config keys
config.LoadOSEnvs(map[string]string{
    "APP_NAME":  "app.name",
    "APP_DEBUG": "app.debug",
    "DB_HOST":   "database.host",
})

config.String("app.name")     // "myapp"
config.Bool("app.debug")      // true
config.String("database.host") // "localhost"

Load from CLI Flags

// Define flags
config.LoadFlags([]string{
    "env:set run environment",
    "debug:bool:enable debug mode",
    "port:int",
    "db.host:database host",
})

// Run: myapp --env prod --debug --port 9090 --db.host postgres.local

config.String("env")     // "prod"
config.Bool("debug")     // true
config.Int("port")       // 9090
config.String("db.host") // "postgres.local"

Set Values

// Set simple value
config.Set("app.name", "newname")

// Set nested value
config.Set("db.host", "localhost")

// Set map data
config.SetData(map[string]any{
    "app": map[string]any{
        "name": "myapp",
        "version": "1.0",
    },
})

Format Drivers

Each format requires importing its driver:

import (
    "github.com/gookit/config/v2/json"  // JSON (default)
    "github.com/gookit/config/v2/yaml"  // YAML
    "github.com/gookit/config/v2/toml"  // TOML
    "github.com/gookit/config/v2/ini"   // INI
    "github.com/gookit/config/v2/json5" // JSON5
    "github.com/gookit/config/v2/properties" // Properties
)

// Add drivers
config.AddDriver(yaml.Driver)
config.AddDriver(toml.Driver)

Note: JSON driver is pre-loaded; others are on-demand.

Common Options

// Parse ENV variables in values
config.WithOptions(config.ParseEnv)

// Parse default values from struct tags
config.WithOptions(config.ParseDefault)

// Make config read-only
config.WithOptions(config.Readonly)

// Enable data cache
config.WithOptions(config.EnableCache)

// Multiple options
config.WithOptions(config.ParseEnv, config.ParseDefault)

Basic Patterns

Application Config

// config.yaml
app:
  name: myapp
  env: ${APP_ENV|dev}
  debug: ${DEBUG|false}

server:
  port: ${PORT|8080}
  timeout: 30s

// Load and use
config.WithOptions(config.ParseEnv)
config.AddDriver(yaml.Driver)
config.LoadFiles("config.yaml")

type AppConfig struct {
    App struct {
        Name  string
        Env   string
        Debug bool
    }
    Server struct {
        Port    int
        Timeout string
    }
}

var cfg AppConfig
config.Decode(&cfg)

Environment-Specific Config

// Load base + environment
env := os.Getenv("APP_ENV")
if env == "" {
    env = "dev"
}

config.LoadFiles("config.yaml")
config.LoadExists("config." + env + ".yaml")

// config.yaml - base config
// config.dev.yaml - development overrides
// config.prod.yaml - production overrides

Config with Defaults

type ServerConfig struct {
    Host string `default:"0.0.0.0"`
    Port int    `default:"8080"`
    SSL  bool   `default:"false"`
}

config.WithOptions(config.ParseDefault)

var server ServerConfig
config.BindStruct("server", &server)
// Fields use defaults if not in config

Documentation

• 📘 Loading Config - Load from files, ENV, flags, remote URLs
• 📚 Using Config - Get values, bind structs, type conversions
• 🔧 Advanced Features - Options, events, watching, dumping, instances

API Summary

Loading:

• LoadFiles(files ...string) error
• LoadOSEnvs(map[string]string) error
• LoadFlags(keys []string) error
• LoadRemote(format, url string) error
• LoadData(data ...any) error

Getting:

• Get(key string) any
• String(key string, def ...string) string
• Int(key string, def ...int) int
• Bool(key string, def ...bool) bool
• Float(key string, def ...float64) float64
• Strings(key string) []string
• StringMap(key string) map[string]string

Binding:

• Decode(dst any) error
• BindStruct(key string, dst any) error

Setting:

• Set(key string, val any) error
• SetData(data map[string]any)

Utility:

• Exists(key string) bool
• Data() map[string]any
• DumpTo(io.Writer, format string) error

Resources

• GitHub: https://github.com/gookit/config
• Go Package: https://pkg.go.dev/github.com/gookit/config/v2
• 中文文档: https://github.com/gookit/config/blob/master/README.zh-CN.md

Related Projects

• gookit/ini - INI parser with dotenv support
• gookit/properties - Properties parser
• gookit/goutil - Go utilities