I've always loved the elegance of Go's flag package - how clean and straightforward it is to define and use configuration options. While working on various Go projects, I found myself wanting that same simplicity but with support for YAML configs. I couldn't find anything that preserved this paradigm, so I built zerocfg.
- 🛠️ Simple and flexible API inspired by
flagpackage - 🍳 Boilerplate usage prohibited by design
- 🚦 Early detection of mistyped config keys
- ✨ Multiple configuration sources with priority-based value resolution
- 🕵️‍♂️ Render running configuration with secret protection
- 🧩 Custom option types and sources are supported
go get -u github.com/chaindead/zerocfgpackage main
import (
"fmt"
zfg "github.com/chaindead/zerocfg"
"github.com/chaindead/zerocfg/env"
"github.com/chaindead/zerocfg/yaml"
)
var (
// Configuration variables
path = zfg.Str("config.path", "", "path to yaml conf file", zfg.Alias("c"))
ip = zfg.IP("db.ip", "127.0.0.1", "database location")
port = zfg.Uint("db.port", 5678, "database port")
username = zfg.Str("db.user", "guest", "user of database")
password = zfg.Str("db.password", "qwerty", "password for user", zfg.Secret())
)
func main() {
// Initialize configuration with multiple sources
err := zfg.Parse(
env.New(),
yaml.New(path),
)
if err != nil {
panic(err)
}
fmt.Printf("Connect to %s:%d creds=%s:%s\n", *ip, *port, *username, *password)
// OUTPUT: Connect to 127.0.0.1:5678 creds=guest:qwerty
fmt.Println(zfg.Show())
// CMD: go run ./... -c test.yaml
// OUTPUT:
// config.path = test.yaml (path to yaml conf file)
// db.ip = 127.0.0.1 (database location)
// db.password = <secret> (password for user)
// db.port = 5678 (database port)
// db.user = guest (user of database)
}- Dots (
.) are used as separators for hierarchical options. - Option subnames preferred separation is camelCase, underscore (
_), and dash (-) styles.
Example:
zfg.Str("groupOptions.thisOption", "", "camelCase usage")
zfg.Str("group_options.this_option", "", "underscore usage")
zfg.Str("group-options.this-option", "", "dash usage")-
Options are registered at import time. Dynamic (runtime) option registration is not supported
// internal/db/client.go package db import zfg "github.com/chaindead/zerocfg" // good: options registered at import var dbHost = zfg.Str("db.host", "localhost", "called on import") // bad: dynamic registration func AddOption() { zfg.Str("db.dynamic", "", "not supported") }
-
No key duplication is allowed. Each option key must be unique to ensure a single source of truth and avoid boilerplate
-
Simultaneous use of keys and sub-keys (e.g.,
mapandmap.value) are not allowed
If zfg.Parse encounters an unknown value (e.g. variable not registered as an option), it returns an error.
This helps avoid boilerplate and ensures only declared options are used.
But you can ignore unknown values if desired.
err := zfg.Parse(
env.New(),
yaml.New(path),
)
if u, ok := zfg.IsUnknown(err); !ok {
panic(err)
} else {
// u is map <source_name> to slice of unknown keys
fmt.Println(u)
}
envsource does not trigger unknown options to avoid false positives.
- Base values converted via
fmt.Sprint("%v") - If a type has a
String()method, it is used for string conversion (e.g.,time.Duration). - Otherwise, JSON representation is used for complex types (e.g., slices, maps).
For converting any value to string,
zfg.ToStringis used internally.
var ( _ = zfg.Dur("timeout", 5*time.Second, "duration via fmt.Stringer interface") _ = zfg.Floats64("floats", nil, "list via json") ) func main() { _ = zfg.Parse() fmt.Printf(zfg.Show()) // CMD: go run ./... --timeout 10s --floats '[1.1, 2.2, 3.3]' // OUTPUT: // floats = [1.1,2.2,3.3] (list via json) // timeout = 10s (duration via fmt.Stringer interface) }
The configuration system follows a strict priority hierarchy:
- Command-line flags (always highest priority, enabled by default)
- Optional providers in order of addition (first added = higher priority)
- Default values (lowest priority)
For example, if you initialize configuration like this:
zfg.Parse(
env.New(), // Second highest priority (after cli flags)
yaml.New(path), // Third highest priority
)The final value resolution order will be:
- Command-line flags (if provided)
- Providers from arguments of
zfg.Parsein same order as it is passed. - Default values
Important notes:
- Lower priority sources cannot override values from higher priority sources
- All providers except flags are optional
- Provider priority is determined by the order in
Parse()function - Values not found in higher priority sources fall back to lower priority sources
- The flag source is enabled by default and always has the highest priority
- You can define configuration options with aliases for convenient CLI usage
- Values are passed as space-separated arguments (no
=allowed) - Both single dash (
-) and double dash (--) prefixes are supported for flags and their aliases
Example:
path := zfg.Str("config.path", "", "path to yaml conf file", zfg.Alias("c"))You can run your application with:
go run ./... -c test.yaml
# or
go run ./... --config.path test.yaml
In both cases, the value test.yaml will be assigned to config.path.
Environment variables are automatically transformed from the configuration key format:
| Config Key | Environment Variable | Note |
|---|---|---|
| db.user | DB_USER | Basic transformation |
| app.api.key | APP_API_KEY | Multi-level path |
| camelCase.value | CAMELCASE_VALUE | CamelCase handling |
| api-key.secret | APIKEY_SECRET | Dashes removed |
| under_score.value | UNDERSCORE_VALUE | Underscores removed |
The transformation rules:
- Remove special characters (except letters, digits, and dots)
- Replace dots with underscores
- Convert to uppercase
Example:
var list = zfg.Ints("list", nil, "usage example")DB_USER=admin go run main.goWhen you run, dbUser will be set to admin.
- Options use dotted paths to map to YAML keys, supporting hierarchical configuration.
- All naming styles are supported and mapped to YAML keys as written.
Example YAML file:
group:
option: "foo"
numbers:
- 1
- 2
- 3
limits:
max: 10
min: 1Example Go config:
zfg.Str("group.option", "", "hierarchical usage")
zfg.Ints("numbers", nil, "slice of server configs")
zfg.Map("limits", nil, "map of limits")Important
Read this section before implementing custom options or providers.
- All supported option values must have a string representation
- Conversion to string is performed using
zfg.ToString - Types must implement
Set(string); the string passed is produced byToStringand parsing must be compatible - Providers return
map[string]stringwhere values are produced by theconvfunction argument in the provider interface (internallyzfg.ToStringis used)
You can define your own option types by implementing the Value interface and registering them via Any function.
Methods Set and String should be compatible.
// Custom type
type MyType struct{ V string }
func newValue(val MyType, p *MyType) zfg.Value {
*p = val
return p
}
func (m *MyType) Set(s string) error { m.V = s; return nil }
func (m *MyType) Type() string { return "custom" }
func (m *MyType) String() string { return m.V }
func Custom(name string, defVal MyType, desc string, opts ...zfg.OptNode) *MyType {
return zfg.Any(name, defVal, desc, newValue, opts...)
}
// Register custom option
var myOpt = Custom("custom.opt", MyType{"default"}, "custom option")You can add your own configuration sources by implementing the Provider interface.
- If
awaited[name] == true, the name is an option - If
awaited[name] == false, the name is an alias
type MyProvider struct{}
func (p *MyProvider) Type() string { return "my" }
func (p *MyProvider) Provide(awaited map[string]bool, conv func(any) string) (map[string]string, map[string]string, error) {
found := map[string]string{}
unknown := map[string]string{}
// ... fill found/unknown based on awaited ...
return found, unknown, nil
}
// Usage
zfg.Parse(&MyProvider{})For detailed documentation and advanced usage examples, visit our Godoc page.
This project is licensed under the MIT License - see the LICENSE file for details.