{"id":13410883,"url":"https://github.com/go-simpler/env","last_synced_at":"2025-12-30T01:03:14.769Z","repository":{"id":40324828,"uuid":"446519195","full_name":"go-simpler/env","owner":"go-simpler","description":"🔍 Load environment variables into a config struct","archived":false,"fork":false,"pushed_at":"2024-04-17T19:31:57.000Z","size":88,"stargazers_count":53,"open_issues_count":7,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-22T15:20:33.459Z","etag":null,"topics":["12factor","configuration","dependency-free","environment-variables","go","library"],"latest_commit_sha":null,"homepage":"https://go-simpler.org/env","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-simpler.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}},"created_at":"2022-01-10T17:28:03.000Z","updated_at":"2024-05-02T23:01:38.998Z","dependencies_parsed_at":"2024-04-29T12:03:20.616Z","dependency_job_id":null,"html_url":"https://github.com/go-simpler/env","commit_stats":{"total_commits":48,"total_committers":5,"mean_commits":9.6,"dds":0.4375,"last_synced_commit":"f33e5de312606e39a73a261ceb4a50bb6b560fd5"},"previous_names":["junk1tm/env"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-simpler%2Fenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-simpler%2Fenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-simpler%2Fenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-simpler%2Fenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-simpler","download_url":"https://codeload.github.com/go-simpler/env/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221486913,"owners_count":16830966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["12factor","configuration","dependency-free","environment-variables","go","library"],"created_at":"2024-07-30T20:01:09.992Z","updated_at":"2025-12-30T01:03:14.726Z","avatar_url":"https://github.com/go-simpler.png","language":"Go","funding_links":[],"categories":["Configuration"],"sub_categories":["Standard CLI"],"readme":"\u003cdiv align=\"center\"\u003e\n\n![logo](logo.svg)\n\n🔍 Load environment variables into a config struct\n\n[![awesome-go](https://awesome.re/badge.svg)](https://github.com/avelino/awesome-go#configuration)\n[![checks](https://github.com/go-simpler/env/actions/workflows/checks.yml/badge.svg)](https://github.com/go-simpler/env/actions/workflows/checks.yml)\n[![pkg.go.dev](https://pkg.go.dev/badge/go-simpler.org/env.svg)](https://pkg.go.dev/go-simpler.org/env)\n[![goreportcard](https://goreportcard.com/badge/go-simpler.org/env)](https://goreportcard.com/report/go-simpler.org/env)\n[![codecov](https://codecov.io/gh/go-simpler/env/branch/main/graph/badge.svg)](https://codecov.io/gh/go-simpler/env)\n\n\u003c/div\u003e\n\n## 📌 About\n\nThis package is made for apps that [store config in environment variables][1].\nIts purpose is to replace fragmented `os.Getenv` calls in `main.go` with a single struct definition,\nwhich simplifies config management and improves code readability.\n\n## 🚀 Features\n\n* Support for all common types and user-defined types\n* Configurable [source](#source) of environment variables\n* Options: [required](#required), [expand](#expand), [slice separator](#slice-separator), [name separator](#name-separator)\n* Auto-generated [usage message](#usage-message)\n\n## 📦 Install\n\nGo 1.20+\n\n```shell\ngo get go-simpler.org/env\n```\n\n## 📋 Usage\n\n`Load` is the main function of the package.\nIt loads environment variables into the given struct.\n\nThe struct fields must have the `env:\"VAR\"` struct tag,\nwhere `VAR` is the name of the corresponding environment variable.\nUnexported fields are ignored.\n\n```go\nos.Setenv(\"PORT\", \"8080\")\n\nvar cfg struct {\n    Port int `env:\"PORT\"`\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.Port) // 8080\n```\n\n### Supported types\n\n* `int` (any kind)\n* `float` (any kind)\n* `bool`\n* `string`\n* `time.Duration`\n* `encoding.TextUnmarshaler`\n* slices of any type above\n* nested structs of any depth\n\nSee the `strconv.Parse*` functions for the parsing rules.\nUser-defined types can be used by implementing the `encoding.TextUnmarshaler` interface.\n\n### Nested structs\n\nNested struct of any depth level are supported,\nallowing grouping of related environment variables.\n\n```go\nos.Setenv(\"DB_HOST\", \"localhost\")\nos.Setenv(\"DB_PORT\", \"5432\")\n\nvar cfg struct {\n    DB struct {\n        Host string `env:\"DB_HOST\"`\n        Port int    `env:\"DB_PORT\"`\n    }\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.DB.Host) // localhost\nfmt.Println(cfg.DB.Port) // 5432\n```\n\nIf a nested struct has the optional `env:\"PREFIX\"` tag,\nthe environment variables declared by its fields are prefixed with `PREFIX`.\n\n```go\nos.Setenv(\"DB_HOST\", \"localhost\")\nos.Setenv(\"DB_PORT\", \"5432\")\n\nvar cfg struct {\n    DB struct {\n        Host string `env:\"HOST\"`\n        Port int    `env:\"PORT\"`\n    } `env:\"DB_\"`\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.DB.Host) // localhost\nfmt.Println(cfg.DB.Port) // 5432\n```\n\n### Default values\n\nDefault values can be specified using the `default:\"VALUE\"` struct tag.\n\n```go\nos.Unsetenv(\"PORT\")\n\nvar cfg struct {\n    Port int `env:\"PORT\" default:\"8080\"`\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.Port) // 8080\n```\n\n### Required\n\nUse the `required` option to mark an environment variable as required.\nIf it is not set, an error of type `NotSetError` is returned.\n\n```go\nos.Unsetenv(\"PORT\")\n\nvar cfg struct {\n    Port int `env:\"PORT,required\"`\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    var notSetErr *env.NotSetError\n    if errors.As(err, \u0026notSetErr) {\n        fmt.Println(notSetErr) // env: PORT is required but not set\n    }\n}\n```\n\n### Expand\n\nUse the `expand` option to automatically expand the value of an environment variable using `os.Expand`.\n\n```go\nos.Setenv(\"PORT\", \"8080\")\nos.Setenv(\"ADDR\", \"localhost:${PORT}\")\n\nvar cfg struct {\n    Addr string `env:\"ADDR,expand\"`\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.Addr) // localhost:8080\n```\n\n### Slice separator\n\nSpace is the default separator used to parse slice values.\nIt can be changed with `Options.SliceSep`.\n\n```go\nos.Setenv(\"PORTS\", \"8080,8081,8082\")\n\nvar cfg struct {\n    Ports []int `env:\"PORTS\"`\n}\nif err := env.Load(\u0026cfg, \u0026env.Options{SliceSep: \",\"}); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.Ports) // [8080 8081 8082]\n```\n\n### Name separator\n\nBy default, environment variable names are concatenated from nested struct tags as is.\nIf `Options.NameSep` is not empty, it is used as the separator.\n\n```go\nos.Setenv(\"DB_HOST\", \"localhost\")\nos.Setenv(\"DB_PORT\", \"5432\")\n\nvar cfg struct {\n    DB struct {\n        Host string `env:\"HOST\"`\n        Port int    `env:\"PORT\"`\n    } `env:\"DB\"`\n}\nif err := env.Load(\u0026cfg, \u0026env.Options{NameSep: \"_\"}); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.DB.Host) // localhost\nfmt.Println(cfg.DB.Port) // 5432\n```\n\n### Source\n\nBy default, `Load` retrieves environment variables directly from OS.\nTo use a different source, pass an implementation of the `Source` interface via `Options.Source`.\n\n```go\ntype Source interface {\n    LookupEnv(key string) (value string, ok bool)\n}\n```\n\nHere's an example of using `Map`, a `Source` implementation useful in tests.\n\n```go\nm := env.Map{\"PORT\": \"8080\"}\n\nvar cfg struct {\n    Port int `env:\"PORT\"`\n}\nif err := env.Load(\u0026cfg, \u0026env.Options{Source: m}); err != nil {\n    fmt.Println(err)\n}\n\nfmt.Println(cfg.Port) // 8080\n```\n\n### Usage message\n\nThe `Usage` function prints a usage message documenting all defined environment variables.\nAn optional usage string can be added to environment variables with the `usage:\"STRING\"` struct tag.\n\n```go\nos.Unsetenv(\"DB_HOST\")\nos.Unsetenv(\"DB_PORT\")\n\nvar cfg struct {\n    DB struct {\n        Host string `env:\"DB_HOST,required\" usage:\"database host\"`\n        Port int    `env:\"DB_PORT,required\" usage:\"database port\"`\n    }\n    HTTPPort int `env:\"HTTP_PORT\" default:\"8080\" usage:\"http server port\"`\n}\nif err := env.Load(\u0026cfg, nil); err != nil {\n    fmt.Println(err)\n    fmt.Println(\"Usage:\")\n    env.Usage(\u0026cfg, os.Stdout, nil)\n}\n```\n\n```\nUsage:\n  DB_HOST    string  required      database host\n  DB_PORT    int     required      database port\n  HTTP_PORT  int     default 8080  http server port\n```\n\nThe format of the message can be customized by implementing the `Usage([]env.Var, io.Writer, *env.Options)` method.\n\n```go\ntype Config struct{ ... }\n\nfunc (Config) Usage(vars []env.Var, w io.Writer, opts *env.Options) {\n    for v := range vars {\n        // write to w.\n    }\n}\n```\n\n[1]: https://12factor.net/config\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-simpler%2Fenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-simpler%2Fenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-simpler%2Fenv/lists"}