{"id":36721507,"url":"https://github.com/goforj/env","last_synced_at":"2026-01-17T22:25:32.900Z","repository":{"id":328864239,"uuid":"1117096606","full_name":"goforj/env","owner":"goforj","description":"Strongly-typed environment variables for Go with safe defaults, app env helpers, and zero-ceremony configuration.","archived":false,"fork":false,"pushed_at":"2026-01-14T03:55:41.000Z","size":13615,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T20:10:48.607Z","etag":null,"topics":["configuration","developer-experience","dotenv","env","environment-variables","go","goforj","golang","typed-config"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goforj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T20:35:19.000Z","updated_at":"2026-01-14T03:54:08.000Z","dependencies_parsed_at":"2026-01-16T08:00:47.781Z","dependency_job_id":null,"html_url":"https://github.com/goforj/env","commit_stats":null,"previous_names":["goforj/env"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/goforj/env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goforj%2Fenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goforj%2Fenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goforj%2Fenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goforj%2Fenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goforj","download_url":"https://codeload.github.com/goforj/env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goforj%2Fenv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28520380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","developer-experience","dotenv","env","environment-variables","go","goforj","golang","typed-config"],"created_at":"2026-01-12T11:57:36.571Z","updated_at":"2026-01-17T22:25:32.883Z","avatar_url":"https://github.com/goforj.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/logo.png?v=2\" width=\"400\" alt=\"goforj/env logo\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    Typed environment variables for Go - safe defaults, app env helpers, and zero-ceremony configuration.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pkg.go.dev/github.com/goforj/env/v2\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/goforj/env/v2.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/goforj/env/actions\"\u003e\u003cimg src=\"https://github.com/goforj/env/actions/workflows/test.yml/badge.svg\" alt=\"Go Test\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://golang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-1.18+-blue?logo=go\" alt=\"Go version\"\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/tag/goforj/env?label=version\u0026sort=semver\" alt=\"Latest tag\"\u003e\n    \u003ca href=\"https://codecov.io/gh/goforj/env\" \u003e\u003cimg src=\"https://codecov.io/github/goforj/env/graph/badge.svg?token=M7EFUVV1XW\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/goforj/env/v2\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/goforj/env/v2\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003eenv\u003c/code\u003e provides strongly-typed access to environment variables with predictable fallbacks.  \n  Eliminate string parsing, centralize app environment checks, and keep configuration boring.  \n  Designed to feel native to Go - and invisible when things are working.\n\u003c/p\u003e\n\n# Features\n\n- **Strongly typed getters** - `int`, `bool`, `float`, `duration`, slices, maps\n- **Safe fallbacks** - never panic, never accidentally empty\n- **Application environment helpers** - `local`, `staging`, `production`\n- **Minimal dependencies** - Pure Go, lightweight, minimal surface area\n- **Framework-agnostic** - works with any Go app\n- **Enum validation** - constrain values with allowed sets\n- **Predictable behavior** - no magic, no global state surprises\n- **Composable building block** - ideal for config structs and startup wiring\n\n## Why env?\n\nAccessing environment variables in Go often leads to:\n\n- Repeated parsing logic\n- Unsafe string conversions\n- Inconsistent defaults\n- Scattered app environment checks\n\n**env** solves this by providing **typed accessors with fallbacks**, so configuration stays boring and predictable.\n\n## Features\n\n- Strongly typed getters (`int`, `bool`, `duration`, slices, maps)\n- Safe fallbacks (never panic, never empty by accident)\n- App environment helpers (`local`, `staging`, `production`)\n- Zero dependencies\n- Framework-agnostic\n\n## Installation\n\n```bash\ngo get github.com/goforj/env/v2\n````\n\n## Quickstart\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\t\"time\"\n\n\t\"github.com/goforj/env/v2\"\n)\n\nfunc init() {\n\tif err := env.LoadEnvFileIfExists(); err != nil {\n\t\tlog.Fatalf(\"load env: %v\", err)\n\t}\n}\n\nfunc main() {\n    addr := env.Get(\"ADDR\", \"127.0.0.1:8080\")\n    debug := env.GetBool(\"DEBUG\", \"false\")\n    timeout := env.GetDuration(\"HTTP_TIMEOUT\", \"5s\")\n    \n    env.Dump(addr, debug, timeout)\n    // #string \"127.0.0.1:8080\"\n    // #bool false\n    // #time.Duration 5s\n    \n    env.Dump(\"container?\", env.IsContainer())\n    // #string \"container?\"\n    // #bool false\n}\n```\n\n### Full kitchen-sink example\n\nSee [examples/kitchensink/main.go](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.\n\n## Environment file loading\n\nThis package uses `github.com/joho/godotenv` for `.env` file loading.\n\nIt is intentionally composed into the runtime detection and APP_ENV model rather than reimplemented.\n\n## Runnable examples\n\nEvery function has a corresponding runnable example under [`./examples`](./examples).\n\nThese examples are **generated directly from the documentation blocks** of each function, ensuring the docs and code never drift. These are the same examples you see here in the README and GoDoc.\n\nAn automated test executes **every example** to verify it builds and runs successfully.\n\nThis guarantees all examples are valid, up-to-date, and remain functional as the API evolves.\n\n## Container detection at a glance\n\n| Check | True when | Notes |\n|-------|-----------|-------|\n| `IsDocker` | `/.dockerenv` or Docker cgroup markers | Generic Docker container |\n| `IsDockerInDocker` | `/.dockerenv` **and** `docker.sock` | Inner DinD container |\n| `IsDockerHost` | `docker.sock` present, no container cgroups | Host or DinD outer acting as host |\n| `IsContainer` | Any common container signals (Docker, containerd, kube env/cgroup) | General container detection |\n| `IsKubernetes` | `KUBERNETES_SERVICE_HOST` or kubepods cgroup | Inside a Kubernetes pod |\n\n## Environment loading overview\n\nLoadEnvFileIfExists layers env files in a predictable order:\n\n- `.env` is loaded first.\n- `.env.local`, `.env.staging`, or `.env.production` overlays based on `APP_ENV` (defaults to `local` when unset).\n- `.env.testing` overlays when running under tests (APP_ENV=testing or Go test markers).\n- `.env.host` overlays when running on the host or DinD to support host-to-container networking.\n\nLater files override earlier values. Subsequent calls are no-ops.\n\n\u003c!-- api:embed:start --\u003e\n\n### Index\n\n| Group | Functions |\n|------:|-----------|\n| **Application environment** | [GetAppEnv](#getappenv) [IsAppEnv](#isappenv) [IsAppEnvLocal](#isappenvlocal) [IsAppEnvLocalOrStaging](#isappenvlocalorstaging) [IsAppEnvProduction](#isappenvproduction) [IsAppEnvStaging](#isappenvstaging) [IsAppEnvTesting](#isappenvtesting) [IsAppEnvTestingOrLocal](#isappenvtestingorlocal) [SetAppEnv](#setappenv) [SetAppEnvLocal](#setappenvlocal) [SetAppEnvProduction](#setappenvproduction) [SetAppEnvStaging](#setappenvstaging) [SetAppEnvTesting](#setappenvtesting) |\n| **Container detection** | [IsContainer](#iscontainer) [IsDocker](#isdocker) [IsDockerHost](#isdockerhost) [IsDockerInDocker](#isdockerindocker) [IsHostEnvironment](#ishostenvironment) [IsKubernetes](#iskubernetes) |\n| **Debugging** | [Dump](#dump) |\n| **Environment loading** | [IsEnvLoaded](#isenvloaded) [LoadEnvFileIfExists](#loadenvfileifexists) |\n| **Runtime** | [Arch](#arch) [IsBSD](#isbsd) [IsContainerOS](#iscontaineros) [IsLinux](#islinux) [IsMac](#ismac) [IsUnix](#isunix) [IsWindows](#iswindows) [OS](#os) |\n| **Typed getters** | [Get](#get) [GetBool](#getbool) [GetDuration](#getduration) [GetEnum](#getenum) [GetFloat](#getfloat) [GetInt](#getint) [GetInt64](#getint64) [GetMap](#getmap) [GetSlice](#getslice) [GetUint](#getuint) [GetUint64](#getuint64) [MustGet](#mustget) [MustGetBool](#mustgetbool) [MustGetInt](#mustgetint) |\n\n\n## Application environment\n\n### \u003ca id=\"getappenv\"\u003e\u003c/a\u003eGetAppEnv · readonly\n\nGetAppEnv returns the current APP_ENV (empty string if unset).\n\n_Example: simple retrieval_\n\n```go\n_ = os.Setenv(\"APP_ENV\", \"staging\")\nenv.Dump(env.GetAppEnv())\n\n// #string \"staging\"\n```\n\n### \u003ca id=\"isappenv\"\u003e\u003c/a\u003eIsAppEnv · readonly\n\nIsAppEnv checks if APP_ENV matches any of the provided environments.\n\n_Example: match any allowed environment_\n\n```go\n_ = os.Setenv(\"APP_ENV\", \"staging\")\nenv.Dump(env.IsAppEnv(env.Production, env.Staging))\n\n// #bool true\n```\n\n_Example: unmatched environment_\n\n```go\n_ = os.Setenv(\"APP_ENV\", \"local\")\nenv.Dump(env.IsAppEnv(env.Production, env.Staging))\n\n// #bool false\n```\n\n### \u003ca id=\"isappenvlocal\"\u003e\u003c/a\u003eIsAppEnvLocal · readonly\n\nIsAppEnvLocal checks if APP_ENV is \"local\".\n\n```go\n_ = os.Setenv(\"APP_ENV\", env.Local)\nenv.Dump(env.IsAppEnvLocal())\n\n// #bool true\n```\n\n### \u003ca id=\"isappenvlocalorstaging\"\u003e\u003c/a\u003eIsAppEnvLocalOrStaging · readonly\n\nIsAppEnvLocalOrStaging checks if APP_ENV is either \"local\" or \"staging\".\n\n```go\n_ = os.Setenv(\"APP_ENV\", env.Local)\nenv.Dump(env.IsAppEnvLocalOrStaging())\n\n// #bool true\n```\n\n### \u003ca id=\"isappenvproduction\"\u003e\u003c/a\u003eIsAppEnvProduction · readonly\n\nIsAppEnvProduction checks if APP_ENV is \"production\".\n\n```go\n_ = os.Setenv(\"APP_ENV\", env.Production)\nenv.Dump(env.IsAppEnvProduction())\n\n// #bool true\n```\n\n### \u003ca id=\"isappenvstaging\"\u003e\u003c/a\u003eIsAppEnvStaging · readonly\n\nIsAppEnvStaging checks if APP_ENV is \"staging\".\n\n```go\n_ = os.Setenv(\"APP_ENV\", env.Staging)\nenv.Dump(env.IsAppEnvStaging())\n\n// #bool true\n```\n\n### \u003ca id=\"isappenvtesting\"\u003e\u003c/a\u003eIsAppEnvTesting · readonly\n\nIsAppEnvTesting reports whether APP_ENV is \"testing\" or the process looks like `go test`.\n\n_Example: APP_ENV explicitly testing_\n\n```go\n_ = os.Setenv(\"APP_ENV\", env.Testing)\nenv.Dump(env.IsAppEnvTesting())\n\n// #bool true\n```\n\n_Example: no test markers_\n\n```go\n_ = os.Unsetenv(\"APP_ENV\")\nenv.Dump(env.IsAppEnvTesting())\n\n// #bool false (outside of test binaries)\n```\n\n### \u003ca id=\"isappenvtestingorlocal\"\u003e\u003c/a\u003eIsAppEnvTestingOrLocal · readonly\n\nIsAppEnvTestingOrLocal checks if APP_ENV is \"testing\" or \"local\".\n\n```go\n_ = os.Setenv(\"APP_ENV\", env.Testing)\nenv.Dump(env.IsAppEnvTestingOrLocal())\n\n// #bool true\n```\n\n### \u003ca id=\"setappenv\"\u003e\u003c/a\u003eSetAppEnv · mutates-process-env\n\nSetAppEnv sets APP_ENV to a supported value.\n\n_Example: set a supported environment_\n\n```go\n_ = env.SetAppEnv(env.Staging)\nenv.Dump(env.GetAppEnv())\n\n// #string \"staging\"\n```\n\n### \u003ca id=\"setappenvlocal\"\u003e\u003c/a\u003eSetAppEnvLocal · mutates-process-env\n\nSetAppEnvLocal sets APP_ENV to \"local\".\n\n```go\n_ = env.SetAppEnvLocal()\nenv.Dump(env.GetAppEnv())\n\n// #string \"local\"\n```\n\n### \u003ca id=\"setappenvproduction\"\u003e\u003c/a\u003eSetAppEnvProduction · mutates-process-env\n\nSetAppEnvProduction sets APP_ENV to \"production\".\n\n```go\n_ = env.SetAppEnvProduction()\nenv.Dump(env.GetAppEnv())\n\n// #string \"production\"\n```\n\n### \u003ca id=\"setappenvstaging\"\u003e\u003c/a\u003eSetAppEnvStaging · mutates-process-env\n\nSetAppEnvStaging sets APP_ENV to \"staging\".\n\n```go\n_ = env.SetAppEnvStaging()\nenv.Dump(env.GetAppEnv())\n\n// #string \"staging\"\n```\n\n### \u003ca id=\"setappenvtesting\"\u003e\u003c/a\u003eSetAppEnvTesting · mutates-process-env\n\nSetAppEnvTesting sets APP_ENV to \"testing\".\n\n```go\n_ = env.SetAppEnvTesting()\nenv.Dump(env.GetAppEnv())\n\n// #string \"testing\"\n```\n\n## Container detection\n\n### \u003ca id=\"iscontainer\"\u003e\u003c/a\u003eIsContainer · readonly\n\nIsContainer detects common container runtimes (Docker, containerd, Kubernetes, Podman).\n\n_Example: host vs container_\n\n```go\nenv.Dump(env.IsContainer())\n\n// #bool true  (inside most containers)\n// #bool false (on bare-metal/VM hosts)\n```\n\n### \u003ca id=\"isdocker\"\u003e\u003c/a\u003eIsDocker · readonly\n\nIsDocker reports whether the current process is running in a Docker container.\n\n_Example: typical host_\n\n```go\nenv.Dump(env.IsDocker())\n\n// #bool false (unless inside Docker)\n```\n\n### \u003ca id=\"isdockerhost\"\u003e\u003c/a\u003eIsDockerHost · readonly\n\nIsDockerHost reports whether this container behaves like a Docker host.\n\n```go\nenv.Dump(env.IsDockerHost())\n\n// #bool true  (when acting as Docker host)\n// #bool false (for normal containers/hosts)\n```\n\n### \u003ca id=\"isdockerindocker\"\u003e\u003c/a\u003eIsDockerInDocker · readonly\n\nIsDockerInDocker reports whether we are inside a Docker-in-Docker environment.\n\n```go\nenv.Dump(env.IsDockerInDocker())\n\n// #bool true  (inside DinD containers)\n// #bool false (on hosts or non-DinD containers)\n```\n\n### \u003ca id=\"ishostenvironment\"\u003e\u003c/a\u003eIsHostEnvironment · readonly\n\nIsHostEnvironment reports whether the process is running *outside* any\ncontainer or orchestrated runtime.\n\n```go\nenv.Dump(env.IsHostEnvironment())\n\n// #bool true  (on bare-metal/VM hosts)\n// #bool false (inside containers)\n```\n\n### \u003ca id=\"iskubernetes\"\u003e\u003c/a\u003eIsKubernetes · readonly\n\nIsKubernetes reports whether the process is running inside Kubernetes.\n\n```go\nenv.Dump(env.IsKubernetes())\n\n// #bool true  (inside Kubernetes pods)\n// #bool false (elsewhere)\n```\n\n## Debugging\n\n### \u003ca id=\"dump\"\u003e\u003c/a\u003eDump · readonly\n\nDump is a convenience function that calls godump.Dump.\n\n_Example: integers_\n\n```go\nnums := []int{1, 2, 3}\nenv.Dump(nums)\n\n// #[]int [\n//   0 =\u003e 1 #int\n//   1 =\u003e 2 #int\n//   2 =\u003e 3 #int\n// ]\n```\n\n_Example: multiple values_\n\n```go\nenv.Dump(\"status\", map[string]int{\"ok\": 1, \"fail\": 0})\n\n// #string \"status\"\n// #map[string]int [\n//   \"fail\" =\u003e 0 #int\n//   \"ok\"   =\u003e 1 #int\n// ]\n```\n\n## Environment loading\n\n### \u003ca id=\"isenvloaded\"\u003e\u003c/a\u003eIsEnvLoaded · readonly\n\nIsEnvLoaded reports whether LoadEnvFileIfExists was executed in this process.\n\n```go\nenv.Dump(env.IsEnvLoaded())\n\n// #bool true  (after LoadEnvFileIfExists)\n// #bool false (otherwise)\n```\n\n### \u003ca id=\"loadenvfileifexists\"\u003e\u003c/a\u003eLoadEnvFileIfExists · mutates-process-env\n\nLoadEnvFileIfExists loads .env with optional layering for .env.local/.env.staging/.env.production,\nplus .env.testing/.env.host when present.\n\n_Example: test-specific env file_\n\n```go\ntmp, _ := os.MkdirTemp(\"\", \"envdoc\")\n_ = os.WriteFile(filepath.Join(tmp, \".env.testing\"), []byte(\"PORT=9090\\nAPP_DEBUG=0\"), 0o644)\n_ = os.Chdir(tmp)\n_ = os.Setenv(\"APP_ENV\", env.Testing)\n\n_ = env.LoadEnvFileIfExists()\nenv.Dump(os.Getenv(\"PORT\"))\n\n// #string \"9090\"\n```\n\n_Example: default .env on a host_\n\n```go\n_ = os.WriteFile(\".env\", []byte(\"SERVICE=api\\nAPP_DEBUG=3\"), 0o644)\n_ = env.LoadEnvFileIfExists()\nenv.Dump(os.Getenv(\"SERVICE\"))\n\n// #string \"api\"\n```\n\n## Runtime\n\n### \u003ca id=\"arch\"\u003e\u003c/a\u003eArch · readonly\n\nArch returns the CPU architecture the binary is running on.\n\n_Example: print GOARCH_\n\n```go\nenv.Dump(env.Arch())\n\n// #string \"amd64\"\n// #string \"arm64\"\n```\n\n### \u003ca id=\"isbsd\"\u003e\u003c/a\u003eIsBSD · readonly\n\nIsBSD reports whether the runtime OS is any BSD variant.\n\n```go\nenv.Dump(env.IsBSD())\n\n// #bool true  (on BSD variants)\n// #bool false (elsewhere)\n```\n\n### \u003ca id=\"iscontaineros\"\u003e\u003c/a\u003eIsContainerOS · readonly\n\nIsContainerOS reports whether this OS is *typically* used as a container base.\n\n```go\nenv.Dump(env.IsContainerOS())\n\n// #bool true  (on Linux)\n// #bool false (on macOS/Windows)\n```\n\n### \u003ca id=\"islinux\"\u003e\u003c/a\u003eIsLinux · readonly\n\nIsLinux reports whether the runtime OS is Linux.\n\n```go\nenv.Dump(env.IsLinux())\n\n// #bool true  (on Linux)\n// #bool false (on other OSes)\n```\n\n### \u003ca id=\"ismac\"\u003e\u003c/a\u003eIsMac · readonly\n\nIsMac reports whether the runtime OS is macOS (Darwin).\n\n```go\nenv.Dump(env.IsMac())\n\n// #bool true  (on macOS)\n// #bool false (elsewhere)\n```\n\n### \u003ca id=\"isunix\"\u003e\u003c/a\u003eIsUnix · readonly\n\nIsUnix reports whether the OS is Unix-like.\n\n```go\nenv.Dump(env.IsUnix())\n\n// #bool true  (on Unix-like OSes)\n// #bool false (e.g., on Windows or Plan 9)\n```\n\n### \u003ca id=\"iswindows\"\u003e\u003c/a\u003eIsWindows · readonly\n\nIsWindows reports whether the runtime OS is Windows.\n\n```go\nenv.Dump(env.IsWindows())\n\n// #bool true  (on Windows)\n// #bool false (elsewhere)\n```\n\n### \u003ca id=\"os\"\u003e\u003c/a\u003eOS · readonly\n\nOS returns the current operating system identifier.\n\n_Example: inspect GOOS_\n\n```go\nenv.Dump(env.OS())\n\n// #string \"linux\"   (on Linux)\n// #string \"darwin\"  (on macOS)\n// #string \"windows\" (on Windows)\n```\n\n## Typed getters\n\n### \u003ca id=\"get\"\u003e\u003c/a\u003eGet · readonly\n\nGet returns the environment variable for key or fallback when empty.\n\n_Example: fallback when unset_\n\n```go\nos.Unsetenv(\"DB_HOST\")\nhost := env.Get(\"DB_HOST\", \"localhost\")\nenv.Dump(host)\n\n// #string \"localhost\"\n```\n\n_Example: prefer existing value_\n\n```go\n_ = os.Setenv(\"DB_HOST\", \"db.internal\")\nhost = env.Get(\"DB_HOST\", \"localhost\")\nenv.Dump(host)\n\n// #string \"db.internal\"\n```\n\n### \u003ca id=\"getbool\"\u003e\u003c/a\u003eGetBool · readonly\n\nGetBool parses a boolean from an environment variable or fallback string.\n\n_Example: numeric truthy_\n\n```go\n_ = os.Setenv(\"DEBUG\", \"1\")\ndebug := env.GetBool(\"DEBUG\", \"false\")\nenv.Dump(debug)\n\n// #bool true\n```\n\n_Example: fallback string_\n\n```go\nos.Unsetenv(\"DEBUG\")\ndebug = env.GetBool(\"DEBUG\", \"false\")\nenv.Dump(debug)\n\n// #bool false\n```\n\n### \u003ca id=\"getduration\"\u003e\u003c/a\u003eGetDuration · readonly\n\nGetDuration parses a Go duration string (e.g. \"5s\", \"10m\", \"1h\").\n\n_Example: override request timeout_\n\n```go\n_ = os.Setenv(\"HTTP_TIMEOUT\", \"30s\")\ntimeout := env.GetDuration(\"HTTP_TIMEOUT\", \"5s\")\nenv.Dump(timeout)\n\n// #time.Duration 30s\n```\n\n_Example: fallback when unset_\n\n```go\nos.Unsetenv(\"HTTP_TIMEOUT\")\ntimeout = env.GetDuration(\"HTTP_TIMEOUT\", \"5s\")\nenv.Dump(timeout)\n\n// #time.Duration 5s\n```\n\n### \u003ca id=\"getenum\"\u003e\u003c/a\u003eGetEnum · readonly\n\nGetEnum ensures the environment variable's value is in the allowed list.\n\n_Example: accept only staged environments_\n\n```go\n_ = os.Setenv(\"APP_ENV\", \"production\")\nappEnv := env.GetEnum(\"APP_ENV\", \"local\", []string{\"local\", \"staging\", \"production\"})\nenv.Dump(appEnv)\n\n// #string \"production\"\n```\n\n_Example: fallback when unset_\n\n```go\nos.Unsetenv(\"APP_ENV\")\nappEnv = env.GetEnum(\"APP_ENV\", \"local\", []string{\"local\", \"staging\", \"production\"})\nenv.Dump(appEnv)\n\n// #string \"local\"\n```\n\n### \u003ca id=\"getfloat\"\u003e\u003c/a\u003eGetFloat · readonly\n\nGetFloat parses a float64 from an environment variable or fallback string.\n\n_Example: override threshold_\n\n```go\n_ = os.Setenv(\"THRESHOLD\", \"0.82\")\nthreshold := env.GetFloat(\"THRESHOLD\", \"0.75\")\nenv.Dump(threshold)\n\n// #float64 0.82\n```\n\n_Example: fallback with decimal string_\n\n```go\nos.Unsetenv(\"THRESHOLD\")\nthreshold = env.GetFloat(\"THRESHOLD\", \"0.75\")\nenv.Dump(threshold)\n\n// #float64 0.75\n```\n\n### \u003ca id=\"getint\"\u003e\u003c/a\u003eGetInt · readonly\n\nGetInt parses an int from an environment variable or fallback string.\n\n_Example: fallback used_\n\n```go\nos.Unsetenv(\"PORT\")\nport := env.GetInt(\"PORT\", \"3000\")\nenv.Dump(port)\n\n// #int 3000\n```\n\n_Example: env overrides fallback_\n\n```go\n_ = os.Setenv(\"PORT\", \"8080\")\nport = env.GetInt(\"PORT\", \"3000\")\nenv.Dump(port)\n\n// #int 8080\n```\n\n### \u003ca id=\"getint64\"\u003e\u003c/a\u003eGetInt64 · readonly\n\nGetInt64 parses an int64 from an environment variable or fallback string.\n\n_Example: parse large numbers safely_\n\n```go\n_ = os.Setenv(\"MAX_SIZE\", \"1048576\")\nsize := env.GetInt64(\"MAX_SIZE\", \"512\")\nenv.Dump(size)\n\n// #int64 1048576\n```\n\n_Example: fallback when unset_\n\n```go\nos.Unsetenv(\"MAX_SIZE\")\nsize = env.GetInt64(\"MAX_SIZE\", \"512\")\nenv.Dump(size)\n\n// #int64 512\n```\n\n### \u003ca id=\"getmap\"\u003e\u003c/a\u003eGetMap · readonly\n\nGetMap parses key=value pairs separated by commas into a map.\n\n_Example: parse throttling config_\n\n```go\n_ = os.Setenv(\"LIMITS\", \"read=10, write=5, burst=20\")\nlimits := env.GetMap(\"LIMITS\", \"\")\nenv.Dump(limits)\n\n// #map[string]string [\n//  \"burst\" =\u003e \"20\" #string\n//  \"read\"  =\u003e \"10\" #string\n//  \"write\" =\u003e \"5\" #string\n// ]\n```\n\n_Example: returns empty map when unset or blank_\n\n```go\nos.Unsetenv(\"LIMITS\")\nlimits = env.GetMap(\"LIMITS\", \"\")\nenv.Dump(limits)\n\n// #map[string]string []\n```\n\n### \u003ca id=\"getslice\"\u003e\u003c/a\u003eGetSlice · readonly\n\nGetSlice splits a comma-separated string into a []string with trimming.\n\n_Example: trimmed addresses_\n\n```go\n_ = os.Setenv(\"PEERS\", \"10.0.0.1, 10.0.0.2\")\npeers := env.GetSlice(\"PEERS\", \"\")\nenv.Dump(peers)\n\n// #[]string [\n//  0 =\u003e \"10.0.0.1\" #string\n//  1 =\u003e \"10.0.0.2\" #string\n// ]\n```\n\n_Example: empty becomes empty slice_\n\n```go\nos.Unsetenv(\"PEERS\")\npeers = env.GetSlice(\"PEERS\", \"\")\nenv.Dump(peers)\n\n// #[]string []\n```\n\n### \u003ca id=\"getuint\"\u003e\u003c/a\u003eGetUint · readonly\n\nGetUint parses a uint from an environment variable or fallback string.\n\n_Example: defaults to fallback when missing_\n\n```go\nos.Unsetenv(\"WORKERS\")\nworkers := env.GetUint(\"WORKERS\", \"4\")\nenv.Dump(workers)\n\n// #uint 4\n```\n\n_Example: uses provided unsigned value_\n\n```go\n_ = os.Setenv(\"WORKERS\", \"16\")\nworkers = env.GetUint(\"WORKERS\", \"4\")\nenv.Dump(workers)\n\n// #uint 16\n```\n\n### \u003ca id=\"getuint64\"\u003e\u003c/a\u003eGetUint64 · readonly\n\nGetUint64 parses a uint64 from an environment variable or fallback string.\n\n_Example: high range values_\n\n```go\n_ = os.Setenv(\"MAX_ITEMS\", \"5000\")\nmaxItems := env.GetUint64(\"MAX_ITEMS\", \"100\")\nenv.Dump(maxItems)\n\n// #uint64 5000\n```\n\n_Example: fallback when unset_\n\n```go\nos.Unsetenv(\"MAX_ITEMS\")\nmaxItems = env.GetUint64(\"MAX_ITEMS\", \"100\")\nenv.Dump(maxItems)\n\n// #uint64 100\n```\n\n### \u003ca id=\"mustget\"\u003e\u003c/a\u003eMustGet · panic\n\nMustGet returns the value of key or panics if missing/empty.\n\n_Example: required secret_\n\n```go\n_ = os.Setenv(\"API_SECRET\", \"s3cr3t\")\nsecret := env.MustGet(\"API_SECRET\")\nenv.Dump(secret)\n\n// #string \"s3cr3t\"\n```\n\n_Example: panic on missing value_\n\n```go\nos.Unsetenv(\"API_SECRET\")\nsecret = env.MustGet(\"API_SECRET\") // panics: env variable missing: API_SECRET\n```\n\n### \u003ca id=\"mustgetbool\"\u003e\u003c/a\u003eMustGetBool · panic\n\nMustGetBool panics if missing or invalid.\n\n_Example: gate features explicitly_\n\n```go\n_ = os.Setenv(\"FEATURE_ENABLED\", \"true\")\nenabled := env.MustGetBool(\"FEATURE_ENABLED\")\nenv.Dump(enabled)\n\n// #bool true\n```\n\n_Example: panic on invalid value_\n\n```go\n_ = os.Setenv(\"FEATURE_ENABLED\", \"maybe\")\n_ = env.MustGetBool(\"FEATURE_ENABLED\") // panics when parsing\n```\n\n### \u003ca id=\"mustgetint\"\u003e\u003c/a\u003eMustGetInt · panic\n\nMustGetInt panics if the value is missing or not an int.\n\n_Example: ensure numeric port_\n\n```go\n_ = os.Setenv(\"PORT\", \"8080\")\nport := env.MustGetInt(\"PORT\")\nenv.Dump(port)\n\n// #int 8080\n```\n\n_Example: panic on bad value_\n\n```go\n_ = os.Setenv(\"PORT\", \"not-a-number\")\n_ = env.MustGetInt(\"PORT\") // panics when parsing\n```\n\u003c!-- api:embed:end --\u003e\n\n## Philosophy\n\n**env** is part of the **GoForj toolchain** - a collection of focused, composable packages designed to make building Go applications *satisfying*.\n\nNo magic. No globals. No surprises.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoforj%2Fenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoforj%2Fenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoforj%2Fenv/lists"}