Home

Complete Configuration Management for Go

---

Confii loads, merges, validates, and manages configuration from any source — YAML, JSON, TOML, INI, .env files, environment variables, HTTP endpoints, and cloud stores — with type-safe generics, secret resolution, source tracking, drift detection, and versioning.

For an application-sized walkthrough, see the confiify/confii-go-examples CRUD, LocalStack, and Vault/OpenBao companion repository.

Features

• Multi-source loading — YAML, JSON, TOML, INI, .env, env vars, HTTP, S3, SSM, Azure Blob, GCS, IBM COS, Git
• Type-safe generics — Config[T] with cfg.Typed() returning *T and full IDE autocomplete
• Merge strategies — replace, shallow merge, deep merge, append, prepend, intersection, union — with per-path overrides
• Secret resolution — ${secret:key} placeholders from AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault, and OpenBao. The Vault-compatible layer exposes nine auth adapters and uses official HashiCorp auth packages where available; CI live-tests Token and AppRole against OpenBao, while the other adapters have protocol-level tests and require provider-side identity configuration.
• Config composition — Hydra-style _include and _defaults directives with cycle detection
• Environment resolution — Recommended named files or a single file with default + environment sections, with explicit hybrid mode for migrations
• Hook system — key, value, condition, and global hooks applied with full key paths while candidate snapshots are materialized
• Introspection — Explain(), Layers(), Schema(), source tracking, override history
• Drift detection — Diff configs, detect unintended changes, version with rollback
• Dynamic reloading — File watching via fsnotify, incremental reload (mtime + SHA256)
• Observability — Access metrics, event emission, change callbacks
• CLI tool — init, env, connections, load, get, validate, export, diff, debug, explain, plan, lint, docs, and migrate
• Thread-safe — synchronized Config instances, callback-safe lifecycle events, and concurrency-safe process registries/caches

Install

Run go get from an existing Go module. The CLI installation is independent and may run from any directory:

go get github.com/confiify/confii-go/v2@latest
go install github.com/confiify/confii-go/v2/confii@latest
confii --version

Quick Start

Start with an empty Go module, then let the CLI scaffold the project-wide self-configuration and environment files:

mkdir my-service
cd my-service
go mod init example.com/my-service
go get github.com/confiify/confii-go/v2@latest
go install github.com/confiify/confii-go/v2/confii@latest
confii --version
confii init

Choose Separate files (recommended). The result is immediately loadable:

my-service/
├── .confii.yaml
└── config/
    ├── default.yaml
    ├── development.yaml
    └── production.yaml

main.go

package main

import (
    "context"
    "fmt"
    "log"

    confii "github.com/confiify/confii-go/v2"
)

type AppConfig struct {
    App struct {
        Name string `confii:"name"`
    } `confii:"app"`
    Server struct {
        Host string `confii:"host"`
        Port int    `confii:"port"`
    } `confii:"server"`
    Log struct {
        Level string `confii:"level"`
    } `confii:"log"`
}

func main() {
    cfg, err := confii.New[AppConfig]()
    if err != nil {
        log.Fatal(err)
    }
    values, err := cfg.Typed()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s listening on %s:%d (%s)\n",
        values.App.Name, values.Server.Host, values.Server.Port, values.Log.Level)
}

Use the same environment selector in the CLI and the application:

confii env
confii env list
confii plan
go run .

APP_ENV=production confii plan
APP_ENV=production go run .

The full guide explains installation, generated files, safe re-initialization, typed access, runtime overrides, and the one-file environment alternative.

Full Quick Start Guide View Examples

Documentation

Need	Start here
Understand the pipeline	Mental Model
Choose the right path	Learning Paths
Copy a task flow	Recipes
Fix a confusing value or provider issue	Troubleshooting
Customize Confii	Extensibility
Test an application using Confii	Testing Applications
Prepare for production	Production Checklist
Align terminology	Glossary