# Gookit Config

> Simple, full-featured Go application configuration management

- Skill: `gookit/gookit-config` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add gookit/gookit-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gookit/gookit-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gookit (https://skillmd.com/u/gookit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gookit/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

```bash
go get github.com/gookit/config/v2
```

## Quick Start

### Basic Usage

```go
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:**

```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

```go
// 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

```go
// 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

```go
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

```go
// 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

```go
// 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

```go
// 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:

```go
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

```go
// 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

```go
// 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

```go
// 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

```go
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](references/LOADING.md)** - Load from files, ENV, flags, remote URLs
- 📚 **[Using Config](references/USAGE.md)** - Get values, bind structs, type conversions
- 🔧 **[Advanced Features](references/ADVANCED.md)** - 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](https://github.com/gookit/ini) - INI parser with dotenv support
- [gookit/properties](https://github.com/gookit/properties) - Properties parser
- [gookit/goutil](https://github.com/gookit/goutil) - Go utilities