Configuration¶

The framework uses a three-tier configuration system. Values are resolved in this priority order:

CLI flags (highest priority)
Environment variables
TOML config file
Default values (lowest priority)

Using CLI Flags¶

go run main.go --port 3000 --database-dsn sqlite:///myapp.db

Using Environment Variables¶

PORT=3000 DATABASE_DSN=sqlite:///myapp.db go run main.go

Using a TOML Config File¶

To enable TOML configuration, pass a config source to srv.Flags():

import "github.com/urfave/cli/v3"

// Load TOML file as a config source.
// The path is relative to the working directory. If the file
// does not exist, TOML values are silently skipped (CLI and
// env vars still work).
configSource := func(key string) cli.ValueSource {
    return cli.TOMLSourceFromFile("config.toml", key)
}

cmd := &cli.Command{
    Flags:  srv.Flags(configSource),
    Action: srv.Run,
}

The file path ("config.toml") is your choice — you can use any path (e.g., /etc/myapp/config.toml for production). Pass nil to srv.Flags(nil) if you don't need TOML support.

Then create config.toml:

[server]
host = "0.0.0.0"
port = 3000
base_url = "https://myapp.example.com"
max_body_size = 2

[database]
dsn = "sqlite:///data/production.db"

[tls]
mode = "acme"
email = "admin@example.com"

Adding Custom Flags¶

Apps implement the HasFlags interface to declare flags and Configurable to read them:

func (a *App) Flags(configSource func(key string) cli.ValueSource) []cli.Flag {
    return []cli.Flag{
        &cli.StringFlag{
            Name:    "notes-page-size",
            Value:   "20",
            Usage:   "Number of notes per page",
            Sources: cli.EnvVars("NOTES_PAGE_SIZE"),
        },
    }
}

func (a *App) Configure(cfg *burrow.AppConfig, cmd *cli.Command) error {
    a.repo = NewRepository(cfg.DB)
    a.pageSize = int(cmd.Int("notes-page-size"))
    return nil
}

Custom flags are automatically merged into the CLI when you call srv.Flags(). See the urfave/cli flag documentation for all available flag types (StringFlag, IntFlag, BoolFlag, Float64Flag, etc.) and options.

See the TLS guide for HTTPS configuration and the Configuration Reference for the complete flag table.