GoForjUnreleased
Support this libraryStar on GitHub

goforj/env logo

Typed environment variables for Go - safe defaults, app env helpers, and zero-ceremony configuration.

Go ReferenceLicense: MITGo TestGo versionLatest tag

Features ​

env provides strongly-typed access to environment variables with predictable fallbacks. Eliminate string parsing, centralize app environment checks, and keep configuration boring. Designed to feel native to Go - and invisible when things are working.

  • Strongly typed getters - int, bool, float, duration, slices, maps
  • Explicit fallback and required-value APIs - fallback getters stay permissive; MustGet* panics on missing or invalid required values
  • Application environment helpers - local, staging, production
  • Minimal dependencies - Pure Go, lightweight, minimal surface area
  • Framework-agnostic - works with any Go app
  • Enum validation - constrain values with allowed sets
  • Transactional env loading - discovery, parsing, and process updates succeed together or leave the prior environment intact
  • Composable building block - ideal for config structs and startup wiring

Why env? ​

Accessing environment variables in Go often leads to:

  • Repeated parsing logic
  • Unsafe string conversions
  • Inconsistent defaults
  • Scattered app environment checks

env solves this by providing typed accessors with fallbacks, so configuration stays boring and predictable.

Installation ​

bash
go get github.com/goforj/env/v2

Quickstart ​

go
package main

import (
	"log"
	"time"

	"github.com/goforj/env/v2"
)

func init() {
	if err := env.Load(); err != nil {
		log.Fatalf("load env: %v", err)
	}
}

func main() {
	addr := env.Get("ADDR", "127.0.0.1:8080")
	debug := env.GetBool("DEBUG", "false")
	timeout := env.GetDuration("HTTP_TIMEOUT", "5s")

	env.Dump(addr, debug, timeout)
	// #string "127.0.0.1:8080"
	// #bool false
	// #time.Duration 5s

	env.Dump("container?", env.IsContainer())
	// #string "container?"
	// #bool false
}

Scoped prefixes ​

Use Scope when a group of related settings share a common prefix and may also expose named child configs.

go
package main

import (
	"os"

	"github.com/goforj/env/v2"
)

func main() {
	_ = os.Setenv("STORAGE_DRIVER", "local")
	_ = os.Setenv("STORAGE_ROOT", "storage/app/private")
	_ = os.Setenv("STORAGE_PUBLIC_DRIVER", "local")
	_ = os.Setenv("STORAGE_PUBLIC_ROOT", "storage/app/public")
	_ = os.Setenv("STORAGE_AVATARS_DRIVER", "s3")
	_ = os.Setenv("STORAGE_AVATARS_BUCKET", "my-bucket")
	_ = os.Setenv("STORAGE_AVATARS_REGION", "us-east-1")

	storage := env.WithPrefix("STORAGE")

	// Root/default config reads STORAGE_* keys.
	driver := storage.Get("DRIVER", "local")
	root := storage.Get("ROOT", "storage/app/private")

	public := storage.Child("PUBLIC")

	// Child scopes compose STORAGE_<NAME>_* keys.
	publicDriver := public.Get("DRIVER", "local")
	publicRoot := public.Get("ROOT", "storage/app/public")

	// ChildNames discovers named children while ignoring root keys.
	names := storage.ChildNames([]string{
		"DRIVER",
		"ROOT",
		"BUCKET",
		"REGION",
	})

	env.Dump(driver, root, publicDriver, publicRoot, names)
	// #string "local"
	// #string "storage/app/private"
	// #string "local"
	// #string "storage/app/public"
	// #[]string [
	//  0 => "AVATARS" #string
	//  1 => "PUBLIC" #string
	// ]
}

Full kitchen-sink example ​

See examples/kitchensink/main.go for a runnable program that exercises almost every helper (env loading, typed getters, must-getters, runtime + container detection, and the env.Dump wrapper) with deterministic godump output.

Environment loading ​

Load searches for and applies env files in this order:

  • .env
  • .env.local, .env.staging, or .env.production, based on APP_ENV (local by default)
  • .env.host when running on the host or DinD
  • .env.testing when APP_ENV=testing or the process has Go test markers

Each filename is discovered independently, starting in the working directory and checking at most nine ancestors. The nearest regular file wins; regular-file symlinks are followed. Later files override earlier files, while existing process variables override every file. An explicitly empty process variable still counts as existing.

Discovery and parsing finish before any process mutation. Load returns filesystem and parse errors instead of panicking, rolls back a failed environment update, and becomes a no-op after its first success. A failed call leaves IsEnvLoaded false and preserves the prior process environment.

Load, Reload, and IsEnvLoaded synchronize with one another. Direct os.Setenv or os.Unsetenv calls are outside that lock, so applications that mutate the same keys concurrently must coordinate those writes themselves.

Reload always rediscovers the selected files. An unchanged value previously supplied by a file remains file-owned and refreshes from disk. If application code changes its visible value, the process takes ownership and Reload leaves it alone. An unset key is missing again and may be supplied by a file on the next reload; set it to an explicitly empty value when that empty process value must remain authoritative. Any other process value present when Reload discovers a new file key also remains authoritative. If an unchanged file-owned key disappears from every file, its exact pre-load process state is restored, including the difference between unset and explicitly empty. Unrelated variables are untouched. A failed reload preserves the last successful configuration.

An existing process APP_ENV selects the application layer and cannot be replaced by a file. An explicitly empty process APP_ENV selects local files while remaining empty. When the process does not provide APP_ENV, .env may select the application layer; if neither source provides it, the loader defaults it to local. A file-owned APP_ENV is refreshed before layer selection on reload.

v2.6 behavior notes ​

Load and Reload now follow the conventional dotenv precedence rule: existing process variables win and dotenv files supply missing values. Applications that intentionally relied on a file replacing an exported process variable should unset that variable before calling Load.

v2.5 behavior notes ​

The public v2 call shapes are unchanged. The quality pass makes previously implicit failure and reload behavior explicit:

  • Load and Reload return dotenv, filesystem, and environment-application errors rather than panicking.
  • Reload restores removed file keys to their pre-first-load ambient values instead of blindly unsetting them.
  • MustGetInt and MustGetBool now honor their documented contract and panic for missing or invalid values.
  • GetUint parses at the platform's native uint width, and GetMap trims keys and values around =.
  • LoadEnvFileIfExists remains a compatibility alias for Load.

Debug output and secrets ​

Dump intentionally prints the raw values passed to it and performs no redaction. Never pass credentials, tokens, private keys, or other secrets. Loader diagnostics (ENV_DEBUG=3) print only selected file paths and APP_ENV, never dotenv keys or values.

The process environment is the highest-priority configuration source. Sanitize values inherited from an untrusted launcher before calling Load. Child processes normally inherit the resolved environment; construct exec.Cmd.Env explicitly when crossing a trust boundary or when a child must load an independent configuration.

Container detection ​

CheckTrue whenNotes
IsDocker/.dockerenv or Docker cgroup markersGeneric Docker container
IsDockerInDocker/.dockerenv and docker.sockInner DinD container
IsDockerHostdocker.sock present, no container cgroupsHost or DinD outer acting as host
IsContainerAny common container signals (Docker, containerd, Podman marker/cgroup, kube env/cgroup)General container detection
IsKubernetesKUBERNETES_SERVICE_HOST or kubepods cgroupInside a Kubernetes pod

Runnable examples ​

Documented examples are generated directly from function documentation into ./examples, so the README, GoDoc, and example programs share one source. CI regenerates them to detect drift and builds every generated program without build tags. Examples that intentionally demonstrate panic behavior are compiled rather than executed.

Environment file loading ​

This package uses github.com/joho/godotenv for .env file loading.

It is intentionally composed into the runtime detection and APP_ENV model rather than reimplemented.

Philosophy ​

env is part of the GoForj toolchain - a collection of focused, composable packages designed to make building Go applications satisfying.

Small APIs. Explicit process mutation. Predictable failure modes.

API Index ​

GroupFunctions
Application environmentGetAppEnv · IsAppEnv · IsAppEnvLocal · IsAppEnvLocalOrStaging · IsAppEnvProduction · IsAppEnvStaging · IsAppEnvTesting · IsAppEnvTestingOrLocal · SetAppEnv · SetAppEnvLocal · SetAppEnvProduction · SetAppEnvStaging · SetAppEnvTesting
Container detectionIsContainer · IsDocker · IsDockerHost · IsDockerInDocker · IsHostEnvironment · IsKubernetes
DebuggingDump
Environment loadingIsEnvLoaded · Load · LoadEnvFileIfExists · Reload
RuntimeArch · IsBSD · IsContainerOS · IsLinux · IsMac · IsUnix · IsWindows · OS
Typed gettersGet · GetBool · GetDuration · GetEnum · GetFloat · GetInt · GetInt64 · GetMap · GetMapInt · GetSlice · GetUint · GetUint64 · MustGet · MustGetBool · MustGetInt · Scope.Child · Scope.ChildNames · Scope.Get · Scope.GetBool · Scope.GetDuration · Scope.GetEnum · Scope.GetFloat · Scope.GetInt · Scope.GetInt64 · Scope.GetMap · Scope.GetMapInt · Scope.GetSlice · Scope.GetUint · Scope.GetUint64 · Scope.Key · WithPrefix

Application environment ​

GetAppEnv ​

GetAppEnv returns the current APP_ENV (empty string if unset).

Example: simple retrieval

go
_ = os.Setenv("APP_ENV", "staging")
env.Dump(env.GetAppEnv())
// #string "staging"

IsAppEnv ​

IsAppEnv checks if APP_ENV matches any of the provided environments.

Example: match any allowed environment

go
_ = os.Setenv("APP_ENV", "staging")
env.Dump(env.IsAppEnv(env.Production, env.Staging))
// #bool true

Example: unmatched environment

go
_ = os.Setenv("APP_ENV", "local")
env.Dump(env.IsAppEnv(env.Production, env.Staging))
// #bool false

IsAppEnvLocal ​

IsAppEnvLocal checks if APP_ENV is "local".

go
_ = os.Setenv("APP_ENV", env.Local)
env.Dump(env.IsAppEnvLocal())
// #bool true

IsAppEnvLocalOrStaging ​

IsAppEnvLocalOrStaging checks if APP_ENV is either "local" or "staging".

go
_ = os.Setenv("APP_ENV", env.Local)
env.Dump(env.IsAppEnvLocalOrStaging())
// #bool true

IsAppEnvProduction ​

IsAppEnvProduction checks if APP_ENV is "production".

go
_ = os.Setenv("APP_ENV", env.Production)
env.Dump(env.IsAppEnvProduction())
// #bool true

IsAppEnvStaging ​

IsAppEnvStaging checks if APP_ENV is "staging".

go
_ = os.Setenv("APP_ENV", env.Staging)
env.Dump(env.IsAppEnvStaging())
// #bool true

IsAppEnvTesting ​

IsAppEnvTesting reports whether APP_ENV is "testing" or the process looks like go test.

Example: APP_ENV explicitly testing

go
_ = os.Setenv("APP_ENV", env.Testing)
env.Dump(env.IsAppEnvTesting())
// #bool true

Example: no test markers

go
_ = os.Unsetenv("APP_ENV")
env.Dump(env.IsAppEnvTesting())
// #bool false (outside of test binaries)

IsAppEnvTestingOrLocal ​

IsAppEnvTestingOrLocal checks if APP_ENV is "testing" or "local".

go
_ = os.Setenv("APP_ENV", env.Testing)
env.Dump(env.IsAppEnvTestingOrLocal())
// #bool true

SetAppEnv ​

SetAppEnv sets APP_ENV to a supported value.

Example: set a supported environment

go
_ = env.SetAppEnv(env.Staging)
env.Dump(env.GetAppEnv())
// #string "staging"

SetAppEnvLocal ​

SetAppEnvLocal sets APP_ENV to "local".

go
_ = env.SetAppEnvLocal()
env.Dump(env.GetAppEnv())
// #string "local"

SetAppEnvProduction ​

SetAppEnvProduction sets APP_ENV to "production".

go
_ = env.SetAppEnvProduction()
env.Dump(env.GetAppEnv())
// #string "production"

SetAppEnvStaging ​

SetAppEnvStaging sets APP_ENV to "staging".

go
_ = env.SetAppEnvStaging()
env.Dump(env.GetAppEnv())
// #string "staging"

SetAppEnvTesting ​

SetAppEnvTesting sets APP_ENV to "testing".

go
_ = env.SetAppEnvTesting()
env.Dump(env.GetAppEnv())
// #string "testing"

Container detection ​

IsContainer ​

IsContainer detects common container runtimes (Docker, containerd, Kubernetes, Podman).

Example: host vs container

go
env.Dump(env.IsContainer())
// #bool true  (inside most containers)
// #bool false (on bare-metal/VM hosts)

IsDocker ​

IsDocker reports whether the current process is running in a Docker container.

Example: typical host

go
env.Dump(env.IsDocker())
// #bool false (unless inside Docker)

IsDockerHost ​

IsDockerHost reports whether this container behaves like a Docker host.

go
env.Dump(env.IsDockerHost())
// #bool true  (when acting as Docker host)
// #bool false (for normal containers/hosts)

IsDockerInDocker ​

IsDockerInDocker reports whether we are inside a Docker-in-Docker environment.

go
env.Dump(env.IsDockerInDocker())
// #bool true  (inside DinD containers)
// #bool false (on hosts or non-DinD containers)

IsHostEnvironment ​

IsHostEnvironment reports whether the process is running outside any container or orchestrated runtime.

go
env.Dump(env.IsHostEnvironment())
// #bool true  (on bare-metal/VM hosts)
// #bool false (inside containers)

IsKubernetes ​

IsKubernetes reports whether the process is running inside Kubernetes.

go
env.Dump(env.IsKubernetes())
// #bool true  (inside Kubernetes pods)
// #bool false (elsewhere)

Debugging ​

Dump ​

Dump writes complete representations of its arguments to standard output.

Example: integers

go
nums := []int{1, 2, 3}
env.Dump(nums)
// #[]int [
//   0 => 1 #int
//   1 => 2 #int
//   2 => 3 #int
// ]

Example: multiple values

go
env.Dump("status", map[string]int{"ok": 1, "fail": 0})
// #string "status"
// #map[string]int [
//   "fail" => 0 #int
//   "ok"   => 1 #int
// ]

Environment loading ​

IsEnvLoaded ​

IsEnvLoaded reports whether a Load or Reload completed successfully in this process.

go
env.Dump(env.IsEnvLoaded())
// #bool true  (after Load)
// #bool false (otherwise)

Load ​

Load loads the nearest env files with deterministic layering.

Load applies once per process. Existing process values override files, and later files override earlier files for keys absent from the process environment. Discovery and parsing complete before the process environment changes; errors leave both the environment and loader state unchanged. Use Reload to re-read files.

Example: test-specific env file

go
tmp, _ := os.MkdirTemp("", "envdoc")
defer os.RemoveAll(tmp)
originalDirectory, _ := os.Getwd()
defer os.Chdir(originalDirectory)
_ = os.WriteFile(filepath.Join(tmp, ".env.testing"), []byte("PORT=9090\nENV_DEBUG=0"), 0o644)
_ = os.Chdir(tmp)
_ = os.Setenv("APP_ENV", env.Testing)

_ = env.Load()
env.Dump(os.Getenv("PORT"))
// #string "9090"

LoadEnvFileIfExists ​

LoadEnvFileIfExists is a compatibility alias for Load.

go
_ = env.LoadEnvFileIfExists()

Reload ​

Reload re-discovers and transactionally reapplies env files even after Load has run.

Keys loaded from files remain file-owned until application code changes their visible value. Reload refreshes unchanged file-owned keys while preserving process overrides. An unset key is missing and may be supplied by a file again. When a key disappears from all files, Reload restores the process value (including unset versus empty) that existed before the first successful Load. Unrelated process variables are never changed.

Example: refresh changed env files

go
tmp, _ := os.MkdirTemp("", "envdoc")
defer os.RemoveAll(tmp)
originalDirectory, _ := os.Getwd()
defer os.Chdir(originalDirectory)
_ = os.Chdir(tmp)
_ = os.WriteFile(filepath.Join(tmp, ".env"), []byte("SERVICE=api"), 0o644)
_ = env.Load()
_ = os.WriteFile(filepath.Join(tmp, ".env"), []byte("SERVICE=worker"), 0o644)
_ = env.Reload()
env.Dump(os.Getenv("SERVICE"))
// #string "worker"

Runtime ​

Arch ​

Arch returns the CPU architecture the binary is running on.

Example: print GOARCH

go
env.Dump(env.Arch())
// #string "amd64"
// #string "arm64"

IsBSD ​

IsBSD reports whether the runtime OS is any BSD variant.

go
env.Dump(env.IsBSD())
// #bool true  (on BSD variants)
// #bool false (elsewhere)

IsContainerOS ​

IsContainerOS reports whether this OS is typically used as a container base.

go
env.Dump(env.IsContainerOS())
// #bool true  (on Linux)
// #bool false (on macOS/Windows)

IsLinux ​

IsLinux reports whether the runtime OS is Linux.

go
env.Dump(env.IsLinux())
// #bool true  (on Linux)
// #bool false (on other OSes)

IsMac ​

IsMac reports whether the runtime OS is macOS (Darwin).

go
env.Dump(env.IsMac())
// #bool true  (on macOS)
// #bool false (elsewhere)

IsUnix ​

IsUnix reports whether the OS is Unix-like.

go
env.Dump(env.IsUnix())
// #bool true  (on Unix-like OSes)
// #bool false (e.g., on Windows or Plan 9)

IsWindows ​

IsWindows reports whether the runtime OS is Windows.

go
env.Dump(env.IsWindows())
// #bool true  (on Windows)
// #bool false (elsewhere)

OS ​

OS returns the current operating system identifier.

Example: inspect GOOS

go
env.Dump(env.OS())
// #string "linux"   (on Linux)
// #string "darwin"  (on macOS)
// #string "windows" (on Windows)

Typed getters ​

Get ​

Get returns the environment variable for key or fallback when empty.

Example: fallback when unset

go
os.Unsetenv("DB_HOST")
host := env.Get("DB_HOST", "localhost")
env.Dump(host)
// #string "localhost"

Example: prefer existing value

go
_ = os.Setenv("DB_HOST", "db.internal")
host = env.Get("DB_HOST", "localhost")
env.Dump(host)
// #string "db.internal"

GetBool ​

GetBool parses a boolean from an environment variable or fallback string.

Example: numeric truthy

go
_ = os.Setenv("DEBUG", "1")
debug := env.GetBool("DEBUG", "false")
env.Dump(debug)
// #bool true

Example: fallback string

go
os.Unsetenv("DEBUG")
debug = env.GetBool("DEBUG", "false")
env.Dump(debug)
// #bool false

GetDuration ​

GetDuration parses a Go duration string (e.g. "5s", "10m", "1h").

Example: override request timeout

go
_ = os.Setenv("HTTP_TIMEOUT", "30s")
timeout := env.GetDuration("HTTP_TIMEOUT", "5s")
env.Dump(timeout)
// #time.Duration 30s

Example: fallback when unset

go
os.Unsetenv("HTTP_TIMEOUT")
timeout = env.GetDuration("HTTP_TIMEOUT", "5s")
env.Dump(timeout)
// #time.Duration 5s

GetEnum ​

GetEnum returns the environment value when allowed and fallback otherwise.

Example: accept only staged environments

go
_ = os.Setenv("APP_ENV", "production")
appEnv := env.GetEnum("APP_ENV", "local", []string{"local", "staging", "production"})
env.Dump(appEnv)
// #string "production"

Example: fallback when unset

go
os.Unsetenv("APP_ENV")
appEnv = env.GetEnum("APP_ENV", "local", []string{"local", "staging", "production"})
env.Dump(appEnv)
// #string "local"

GetFloat ​

GetFloat parses a float64 from an environment variable or fallback string.

Example: override threshold

go
_ = os.Setenv("THRESHOLD", "0.82")
threshold := env.GetFloat("THRESHOLD", "0.75")
env.Dump(threshold)
// #float64 0.82

Example: fallback with decimal string

go
os.Unsetenv("THRESHOLD")
threshold = env.GetFloat("THRESHOLD", "0.75")
env.Dump(threshold)
// #float64 0.75

GetInt ​

GetInt parses an int from an environment variable or fallback string.

Example: fallback used

go
os.Unsetenv("PORT")
port := env.GetInt("PORT", "3000")
env.Dump(port)
// #int 3000

Example: env overrides fallback

go
_ = os.Setenv("PORT", "8080")
port = env.GetInt("PORT", "3000")
env.Dump(port)
// #int 8080

GetInt64 ​

GetInt64 parses an int64 from an environment variable or fallback string.

Example: parse large numbers safely

go
_ = os.Setenv("MAX_SIZE", "1048576")
size := env.GetInt64("MAX_SIZE", "512")
env.Dump(size)
// #int64 1048576

Example: fallback when unset

go
os.Unsetenv("MAX_SIZE")
size = env.GetInt64("MAX_SIZE", "512")
env.Dump(size)
// #int64 512

GetMap ​

GetMap parses trimmed key=value pairs separated by commas into a map.

Example: parse throttling config

go
_ = os.Setenv("LIMITS", "read=10, write=5, burst=20")
limits := env.GetMap("LIMITS", "")
env.Dump(limits)
// #map[string]string [
//  "burst" => "20" #string
//  "read"  => "10" #string
//  "write" => "5" #string
// ]

Example: returns empty map when unset or blank

go
os.Unsetenv("LIMITS")
limits = env.GetMap("LIMITS", "")
env.Dump(limits)
// #map[string]string []

GetMapInt ​

GetMapInt parses key=int pairs separated by commas into a map. Invalid, missing, or non-positive values fall back to defaultValue.

Example: parse worker queue weights

go
_ = os.Setenv("QUEUE_WEIGHTS", "critical=6, default=3, low=1")
weights := env.GetMapInt("QUEUE_WEIGHTS", "", 1)
env.Dump(weights)
// #map[string]int [
//  "critical" => 6 #int
//  "default"  => 3 #int
//  "low"      => 1 #int
// ]

Example: invalid values use defaultValue

go
os.Unsetenv("QUEUE_WEIGHTS")
weights = env.GetMapInt("QUEUE_WEIGHTS", "critical=,default=0,low=nope,misc", 2)
env.Dump(weights)
// #map[string]int [
//  "critical" => 2 #int
//  "default"  => 2 #int
//  "low"      => 2 #int
//  "misc"     => 2 #int
// ]

GetSlice ​

GetSlice splits a comma-separated string into a []string with trimming.

Example: trimmed addresses

go
_ = os.Setenv("PEERS", "10.0.0.1, 10.0.0.2")
peers := env.GetSlice("PEERS", "")
env.Dump(peers)
// #[]string [
//  0 => "10.0.0.1" #string
//  1 => "10.0.0.2" #string
// ]

Example: empty becomes empty slice

go
os.Unsetenv("PEERS")
peers = env.GetSlice("PEERS", "")
env.Dump(peers)
// #[]string []

GetUint ​

GetUint parses a uint from an environment variable or fallback string.

Example: defaults to fallback when missing

go
os.Unsetenv("WORKERS")
workers := env.GetUint("WORKERS", "4")
env.Dump(workers)
// #uint 4

Example: uses provided unsigned value

go
_ = os.Setenv("WORKERS", "16")
workers = env.GetUint("WORKERS", "4")
env.Dump(workers)
// #uint 16

GetUint64 ​

GetUint64 parses a uint64 from an environment variable or fallback string.

Example: high range values

go
_ = os.Setenv("MAX_ITEMS", "5000")
maxItems := env.GetUint64("MAX_ITEMS", "100")
env.Dump(maxItems)
// #uint64 5000

Example: fallback when unset

go
os.Unsetenv("MAX_ITEMS")
maxItems = env.GetUint64("MAX_ITEMS", "100")
env.Dump(maxItems)
// #uint64 100

MustGet ​

MustGet returns the value of key or panics if missing/empty.

Example: required secret

go
_ = os.Setenv("API_SECRET", "s3cr3t")
secret := env.MustGet("API_SECRET")
env.Dump(secret)
// #string "s3cr3t"

Example: panic on missing value

go
os.Unsetenv("API_SECRET")
secret = env.MustGet("API_SECRET") // panics: env variable missing: API_SECRET

MustGetBool ​

MustGetBool returns a required bool or panics when the value is missing or invalid.

Example: gate features explicitly

go
_ = os.Setenv("FEATURE_ENABLED", "true")
enabled := env.MustGetBool("FEATURE_ENABLED")
env.Dump(enabled)
// #bool true

Example: panic on invalid value

go
_ = os.Setenv("FEATURE_ENABLED", "maybe")
_ = env.MustGetBool("FEATURE_ENABLED") // panics when parsing

MustGetInt ​

MustGetInt returns a required int or panics when the value is missing or invalid.

Example: ensure numeric port

go
_ = os.Setenv("PORT", "8080")
port := env.MustGetInt("PORT")
env.Dump(port)
// #int 8080

Example: panic on bad value

go
_ = os.Setenv("PORT", "not-a-number")
_ = env.MustGetInt("PORT") // panics when parsing

Scope.Child ​

Child returns a new scope rooted at the current prefix plus name.

Example: named child scope

go
_ = os.Setenv("STORAGE_PUBLIC_ROOT", "storage/app/public")

public := env.WithPrefix("STORAGE").Child("PUBLIC")
env.Dump(
	public.Key("ROOT"),
	public.Get("ROOT", "storage/app/public"),
)
// #string "STORAGE_PUBLIC_ROOT"
// #string "storage/app/public"

Scope.ChildNames ​

ChildNames discovers named child scopes under the current prefix.

Example: discover child names

go
_ = os.Setenv("STORAGE_DRIVER", "local")
_ = os.Setenv("STORAGE_ROOT", "storage/app/private")
_ = os.Setenv("STORAGE_PUBLIC_ROOT", "storage/app/public")
_ = os.Setenv("STORAGE_AVATARS_BUCKET", "my-bucket")
_ = os.Setenv("STORAGE_AVATARS_REGION", "us-east-1")

names := env.WithPrefix("STORAGE").ChildNames([]string{
	"DRIVER",
	"ROOT",
	"BUCKET",
	"REGION",
})
env.Dump(names)
// #[]string [
//  0 => "AVATARS" #string
//  1 => "PUBLIC" #string
// ]

Scope.Get ​

Get returns the string value for key within the scope.

Scope.GetBool ​

GetBool returns the bool value for key within the scope.

Scope.GetDuration ​

GetDuration returns the duration value for key within the scope.

Scope.GetEnum ​

GetEnum returns the enum value for key within the scope.

Scope.GetFloat ​

GetFloat returns the float64 value for key within the scope.

Scope.GetInt ​

GetInt returns the int value for key within the scope.

Scope.GetInt64 ​

GetInt64 returns the int64 value for key within the scope.

Scope.GetMap ​

GetMap returns the string map value for key within the scope.

Scope.GetMapInt ​

GetMapInt returns the int map value for key within the scope.

Scope.GetSlice ​

GetSlice returns the string slice value for key within the scope.

Scope.GetUint ​

GetUint returns the uint value for key within the scope.

Scope.GetUint64 ​

GetUint64 returns the uint64 value for key within the scope.

Scope.Key ​

Key builds the fully qualified environment key for key within the scope.

WithPrefix ​

WithPrefix returns a scope rooted at prefix after minimal normalization.

Example: root scope access

go
_ = os.Setenv("STORAGE_DRIVER", "local")
_ = os.Setenv("STORAGE_ROOT", "storage/app/private")

storage := env.WithPrefix(" STORAGE ")
env.Dump(
	storage.Key("DRIVER"),
	storage.Get("DRIVER", "s3"),
	storage.Get("ROOT", "storage/app/private"),
)
// #string "STORAGE_DRIVER"
// #string "local"
// #string "storage/app/private"

Development ​

Use make test for the root module, make vet for static checks, and make generate to refresh generated documentation. The examples directory is a separate Go module and can be tested from that directory when changed.

License ​

MIT