How to load .env files
A .env file sets environment variables for a run, so flags bound to those variables pick up its values. This guide loads the conventional .env and .env.local pair, keeps the host environment in charge, loads named files, and loads a file whose location comes from a flag.
The running example is the multiformat and dotenv example.
Load .env and .env.local from the working directory
Section titled “Load .env and .env.local from the working directory”Call Dotenv() on the application builder. The example’s flags read their values from environment variables:
type CLI struct { ServiceName conga.OptionalFlag[string] `default:"api-svc" env:"SERVICE_NAME" safe:"true"` Port conga.OptionalFlag[int] `default:"8080" env:"PORT" range:"1..65535" safe:"true" short:"p"` DatabaseURL conga.OptionalFlag[string] `env:"DATABASE_URL" help:"Database connection" short:"d"` MaxWorkers conga.OptionalFlag[int] `default:"4" env:"MAX_WORKERS" help:"Worker thread count" range:"1.." safe:"true"` APIKey conga.OptionalFlag[string] `env:"API_KEY" help:"API key loaded from .env.local"`}
func main() { app := conga.New[CLI](). Name("multiformat-and-dotenv"). EnableWhy(). Dotenv()
if err := app.Run(); err != nil { app.Exit(err) }}The program reads .env, then .env.local, from the working directory. A value in .env.local replaces the same key from .env, and ${VAR} expands from keys defined earlier:
# Database and service defaults (variable expansion supported)DB_HOST=localhostDATABASE_URL=postgres://${DB_HOST}:5432/dbPORT=8000SERVICE_NAME='local svc'API_KEY=from-env# Machine-local values, never committed to source control; API_KEY overrides .envAPI_KEY=local-dev-key-42The example prints each resolved value:
$ multiformat-and-dotenv --service-name string local svc ● env SERVICE_NAME -p, --port int 8000 ● env PORT -d, --database-url string postgres://localhost:5432/db ● env DATABASE_URL --max-workers int 4 · default --api-key string local-dev-key-42 ● env API_KEY--why names the file behind each value:
$ multiformat-and-dotenv --whyValue provenance for "multiformat-and-dotenv":
FLAG VALUE SOURCE ENV CONFIG PATH --service-name local svc env (.env) SERVICE_NAME service-name --port 8000 env (.env) PORT port --database-url ██████ env (.env) DATABASE_URL database-url --max-workers 4 default MAX_WORKERS max-workers --api-key ██████ env (.env.local) API_KEY api-keyvalues are redacted — tag fields safe:"true" to displayWhen either file is missing, the program skips it, so the same binary runs where the environment comes from the host alone.
Let the host environment win
Section titled “Let the host environment win”A variable already set in the shell, container, or CI runner keeps its value, and the files fill in only what the host leaves unset. --why shows a host value as plain env:
$ PORT=9090 multiformat-and-dotenv --whyValue provenance for "multiformat-and-dotenv":
FLAG VALUE SOURCE ENV CONFIG PATH --service-name local svc env (.env) SERVICE_NAME service-name --port 9090 env PORT portvalues are redacted — tag fields safe:"true" to displayExpansion follows the same rule. With DB_HOST=db.prod on the host, ${DB_HOST} in .env expands to the host value:
$ DB_HOST=db.prod multiformat-and-dotenv -d, --database-url string postgres://db.prod:5432/db ● env DATABASE_URLLoad named files
Section titled “Load named files”Pass paths to Dotenv to load exactly those files, in order. A later file replaces keys from an earlier one:
app.Dotenv("config/base.env", "config/secrets.env")In this variation, base.env sets PORT and SERVICE_NAME, and secrets.env replaces SERVICE_NAME:
$ multiformat-and-dotenv --whyValue provenance for "multiformat-and-dotenv":
FLAG VALUE SOURCE ENV CONFIG PATH --service-name secret-svc env (secrets.env) SERVICE_NAME service-name --port 8100 env (base.env) PORT port --database-url unset DATABASE_URL database-url --max-workers 4 default MAX_WORKERS max-workers --api-key unset API_KEY api-key--why shows a file by its name, and adds the directory when two loaded files share a name (env (.env) beside env (sub/.env)).
Every named file must exist:
$ multiformat-and-dotenvError:multiformat-and-dotenv: error: config error: cannot read .env file "config/secrets.env": open config/secrets.env: no such file or directoryErrorLoad a .env from a directory the user picks
Section titled “Load a .env from a directory the user picks”Dotenv fixes its paths when the application starts, before any flag is read. When a flag chooses the location, implement the conga.Bootstrapper interface and tag the flag bootstrap:"true". CONGA binds the flag before calling Bootstrap:
type CLI struct { Dir conga.OptionalFlag[string] `bootstrap:"true" default:"." help:"Project directory" safe:"true"` ServiceName conga.OptionalFlag[string] `default:"api-svc" env:"SERVICE_NAME" safe:"true"` Port conga.OptionalFlag[int] `default:"8080" env:"PORT" safe:"true" short:"p"`}
func (c *CLI) Bootstrap(_ context.Context, b *conga.Bootstrap) error { return b.Dotenv(filepath.Join(c.Dir.Get(), ".env"))}--dir sub loads sub/.env, and leaving --dir off loads ./.env:
$ multiformat-and-dotenv --dir sub --whyValue provenance for "multiformat-and-dotenv":
FLAG VALUE SOURCE ENV CONFIG PATH --dir sub cli - dir --service-name api-svc default SERVICE_NAME service-name --port 8200 env (.env) PORT portLike Dotenv(), Bootstrap.Dotenv skips a missing file. Called with no arguments, it reads .env and .env.local from the working directory.
Load a file the user names
Section titled “Load a file the user names”When a flag names the file itself, use Bootstrap.DotenvExplicit, which requires the file to exist:
type CLI struct { EnvFile conga.OptionalFlag[string] `bootstrap:"true" name:"env-file" help:"Path to the environment file"` // ...}
func (c *CLI) Bootstrap(_ context.Context, b *conga.Bootstrap) error { if !c.EnvFile.IsSet() { return nil }
return b.DotenvExplicit(c.EnvFile.Get())}$ multiformat-and-dotenv --env-file nope.envError:multiformat-and-dotenv: error: config error: cannot read .env file "nope.env": open nope.env: no such file or directoryErrorCombine startup and bootstrap loading
Section titled “Combine startup and bootstrap loading”app.Dotenv() and Bootstrap.Dotenv can both run. The host environment still wins, and a file loaded in Bootstrap replaces keys from a startup file. Here Dotenv() loads ./.env and --dir sub adds sub/.env:
$ multiformat-and-dotenv --dir sub --whyValue provenance for "multiformat-and-dotenv":
FLAG VALUE SOURCE ENV CONFIG PATH --dir sub cli - dir --service-name root-svc env (.env) SERVICE_NAME service-name --port 8200 env (sub/.env) PORT portBootstrap also runs for --why and shell completion, so keep it to quick local reads. Bootstrap fields lists the rules for bootstrap-tagged fields.
Test .env loading
Section titled “Test .env loading”Dotenv writes variables into the process environment with os.Setenv. In tests, chain SetenvFunc(t.Setenv) so each test restores the environment when it ends:
app := conga.New[CLI](). Dotenv("testdata/.env"). SetenvFunc(t.Setenv)Tests that load .env files this way change process-wide state, so they run without t.Parallel. How to test a command covers the rest of the test setup.
Know what users see
Section titled “Know what users see”| Situation | Result |
|---|---|
.env or .env.local missing, with Dotenv() or Bootstrap.Dotenv |
Skipped |
A named file missing, with Dotenv(paths...) or Bootstrap.DotenvExplicit |
Config error, exit 1 |
A line without =, such as PORT 8400 |
Config error, exit 1, naming the file and line |
| A file over 16 MiB | Config error, exit 1, naming the size and the limit |
An empty value, such as PORT= |
Treated as unset: the flag falls back to config or its default |
| The host sets the same variable | The host value wins |
Error:multiformat-and-dotenv: error: config error: cannot parse .env file "bad.env": line 1: dotenv error: parsing .env file: missing '=' in statementErrorError:multiformat-and-dotenv: error: config error: cannot read .env file "big.env": file size limit exceeded: file size 17000002 bytes exceeds maximum limit of 16777216 bytesShell completion reads the same files before suggesting values, so .env settings, including feature gates, shape completion the same way they shape a run. A missing or broken file stays quiet during completion and fails the run itself.
Where to go next
Section titled “Where to go next”- Dotenv files: loading rules, the file grammar, and the size limit.
- How to bind environment variables: connect variables to flags.
- How to manage config files: the source below the environment.
- How to load domain documents: the other use of
Bootstrap. - Multiformat and dotenv example: the program used on this page.