Quickstart

Installation

go get github.com/zoobzio/fig

Requires Go 1.24+.

Basic Usage

Define a struct with tags and call Load:

package main

import (
    "log"

    "github.com/zoobzio/fig"
)

type Config struct {
    Host     string   `env:"APP_HOST" default:"localhost"`
    Port     int      `env:"APP_PORT" default:"8080"`
    Debug    bool     `env:"APP_DEBUG"`
    Tags     []string `env:"APP_TAGS"`
    APIKey   string   `env:"API_KEY" required:"true"`
}

func main() {
    var cfg Config
    if err := fig.Load(&cfg); err != nil {
        log.Fatal(err)
    }
    // cfg is now populated
}

Run with:

API_KEY=secret123 go run main.go

Struct Tags

fig recognises four tags:

Resolution order: secret → env → default → zero value.

Adding Secrets

Pass a secret provider to load secrets from external stores:

import (
    "log"

    "github.com/zoobzio/fig"
    "github.com/zoobzio/fig/vault"
)

type Config struct {
    Password string `secret:"db/password"`
}

func main() {
    provider, err := vault.New()
    if err != nil {
        log.Fatal(err)
    }

    var cfg Config
    if err := fig.Load(&cfg, provider); err != nil {
        log.Fatal(err)
    }
}

Secrets take precedence over environment variables. See Secret Providers for details.

Validation

Implement the Validator interface for post-load validation:

type Config struct {
    Port int `env:"APP_PORT" default:"8080"`
}

func (c *Config) Validate() error {
    if c.Port <= 0 || c.Port > 65535 {
        return errors.New("port must be between 1 and 65535")
    }
    return nil
}

fig calls Validate() automatically after loading. See Validation for patterns.

Nested Structs

fig recurses into embedded structs:

type DatabaseConfig struct {
    Host string `env:"DB_HOST" default:"localhost"`
    Port int    `env:"DB_PORT" default:"5432"`
}

type Config struct {
    Database DatabaseConfig
}

Context Support

Use LoadContext for secret provider timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := fig.LoadContext(ctx, &cfg, provider); err != nil {
    log.Fatal(err)
}

Next Steps

• Concepts — understand resolution order and abstraction layers
• Architecture — learn how fig works internally
• Testing — test code that uses fig
• Reference — full API documentation