Goconfig

goconfig is a lightweight Go library that fills structs from:

1. JSON config file(s)
2. Environment variables
3. Command-line flags

It is designed for apps that want production-ready configuration with minimal boilerplate.

Installation

go get github.com/fulldump/goconfig

Quick Start

package main
import (
"log""time""github.com/fulldump/goconfig"
)
typeDBstruct {
Hoststring`usage:"Database host"`Portint`usage:"Database port"`
}
typeConfigstruct {
ServiceNamestring`usage:"Service name"`Timeout time.Duration`usage:"Request timeout"`DBDB
}
funcmain() {
cfg:=Config{
ServiceName: "payments",
Timeout: 5*time.Second,
DB: DB{
Host: "localhost",
Port: 5432,
},
}
iferr:=goconfig.Load(&cfg); err!=nil {
log.Fatal(err)
}
}

If you want legacy one-liner behaviour (exit on error):

goconfig.Read(&cfg)

Copy/Paste Recipes

1) API service

typeConfigstruct {
HTTPPortint`usage:"HTTP port"`Timeout time.Duration`usage:"Request timeout"`DBstruct {
Hoststring`usage:"Database host"`Portint`usage:"Database port"`
}
}
cfg:=Config{HTTPPort: 8080, Timeout: 3*time.Second}
iferr:=goconfig.Load(&cfg); err!=nil {
log.Fatal(err)
}

2) Worker service

typeConfigstruct {
Concurrencyint`usage:"Worker concurrency"`PollEvery time.Duration`usage:"Polling interval"`Queues []string`usage:"Enabled queues"`
}
cfg:=Config{Concurrency: 4, PollEvery: 2*time.Second}
iferr:=goconfig.Load(&cfg); err!=nil {
log.Fatal(err)
}

Environment example:

export QUEUES='["emails", "billing"]'export CONCURRENCY=8

3) CLI tool with deterministic args/env (tests)

cfg:=Config{}
err:=goconfig.Load(&cfg,
goconfig.WithArgs([]string{"-verbose", "-config", "./testdata/config.json"}),
goconfig.WithEnvLookup(func(kstring) (string, bool) {
ifk=="VERBOSE" {
return"true", true
}
return"", false
}),
goconfig.WithoutImplicitConfigFile(),
)

Precedence

Highest priority wins:

1. Command-line flags
2. Environment variables
3. JSON config file(s)
4. Struct default values

If -config is not provided and ./config.json exists in the current working directory, goconfig loads it automatically before env vars and flags.

Multiple Config Files

-config accepts multiple JSON file paths separated by commas. Files are loaded from left to right over the same struct, so later files override values from previous files while omitted fields keep their existing values.

myapp -config ./config.base.json,./config.prod.json,./config.local.json

The same comma-separated format also works with WithConfigFile:

err:=goconfig.Load(&cfg,
goconfig.WithConfigFile("./config.base.json,./config.prod.json"),
)

Environment variables and command-line flags are still applied after all JSON files, so they keep higher precedence.

Naming Convention

Given this struct:

typeConfigstruct {
Appstruct {
Portint
}
}

• Flag name: -app.port
• Environment variable: APP_PORT
• JSON object:

{
"app": {
"port": 8080
}
}

Built-in Flags

• -help: displays generated help with usage and env names
• -config: JSON file path or comma-separated paths to load before env and flags

When -config is not set, goconfig auto-loads config.json if it exists.

Supported Types

• bool
• string
• float32, float64
• int, int32, int64
• uint, uint32, uint64
• slices ([]T, as JSON arrays for env/flags)
• nested structs
• pointers to structs
• time.Duration (duration string like "15s" or nanoseconds)

Public API

Load

Load returns errors instead of exiting. This is the recommended API for libraries and services.

err:=goconfig.Load(&cfg)

Optional behavior can be controlled with options:

• WithArgs([]string)
• WithProgramName("myapp")
• WithConfigFile("/etc/myapp/config.json")
• WithConfigFlagName("settings")
• WithImplicitConfigFile("myconfig.json")
• WithoutImplicitConfigFile()
• WithEnvLookup(func(string) (string, bool))

Read

Read keeps backward compatibility and exits process on error.

goconfig.Read(&cfg)

Why Teams Use goconfig

• Minimal integration cost for existing Go projects
• Predictable override order across local/dev/prod
• Built-in generated help for operations teams
• No external runtime dependencies

Development

go test ./...

For local workflows:

make test
make coverage

Open Source Health

• CI: GitHub Actions (.github/workflows/ci.yml)
• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md
• Release process: RELEASING.md
• Launch/promotion plan: PROMOTION_PLAN.md
• Issue and PR templates: .github/ISSUE_TEMPLATE and .github/pull_request_template.md

Contributing

Issues and pull requests are welcome.

Roadmap

See ROADMAP.md for the proposed adoption roadmap and high-impact issues.

License

MIT License. See LICENSE.