{"id":20986845,"url":"https://github.com/karmaniverous/get-dotenv","last_synced_at":"2026-01-08T07:17:40.301Z","repository":{"id":65153848,"uuid":"584623381","full_name":"karmaniverous/get-dotenv","owner":"karmaniverous","description":"Manage environment variables from dotenv files across multiple environments. Supports async/CLI operations, dynamic variables, custom CLI creation \u0026 more!","archived":false,"fork":false,"pushed_at":"2024-11-18T16:20:21.000Z","size":1382,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T03:52:20.497Z","etag":null,"topics":["async-programming","cli","configuration","development-environment","devops","dotenv-management","environment-variables","javascript","json","nodejs","programming","software-development"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@karmaniverous/get-dotenv","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karmaniverous.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-01-03T04:48:16.000Z","updated_at":"2024-12-25T15:25:02.000Z","dependencies_parsed_at":"2023-02-15T14:31:53.690Z","dependency_job_id":"2504c4fd-9dbd-4f47-bbbd-d58abbf068b8","html_url":"https://github.com/karmaniverous/get-dotenv","commit_stats":{"total_commits":179,"total_committers":1,"mean_commits":179.0,"dds":0.0,"last_synced_commit":"086a3acce37d82abfc5c005a11fd73675bbca808"},"previous_names":[],"tags_count":102,"template":false,"template_full_name":"karmaniverous/npm-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fget-dotenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fget-dotenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fget-dotenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karmaniverous%2Fget-dotenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karmaniverous","download_url":"https://codeload.github.com/karmaniverous/get-dotenv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248514209,"owners_count":21116899,"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":["async-programming","cli","configuration","development-environment","devops","dotenv-management","environment-variables","javascript","json","nodejs","programming","software-development"],"created_at":"2024-11-19T06:15:03.513Z","updated_at":"2026-01-08T07:17:40.294Z","avatar_url":"https://github.com/karmaniverous.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![This is how.](./assets/contributions.png)\n\n\u003e Load, expand, and compose environment variables from a deterministic dotenv cascade, then execute commands under that context. Use get‑dotenv as a library, a CLI, or a plugin‑first host to build dotenv‑aware tooling with cross‑platform shell control, CI‑friendly capture, and clear diagnostics.\n\n# get-dotenv\n\n[![npm version](https://img.shields.io/npm/v/@karmaniverous/get-dotenv.svg)](https://www.npmjs.com/package/@karmaniverous/get-dotenv)\n![Node Current](https://img.shields.io/node/v/@karmaniverous/get-dotenv)\n[![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/get-dotenv)\n[![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](./CHANGELOG.md)\n[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](./LICENSE)\n\nget‑dotenv helps you:\n\n- Load and merge env vars from a deterministic cascade (global/env × public/private) across multiple paths.\n- Expand values recursively with defaults.\n- Add dynamic variables (JS/TS) that compute from the composed env.\n- Run commands with normalized shell behavior and a consistent child environment.\n- Compose your own CLI from shipped plugins or your own.\n\nSee full guides:\n\n- [Getting started](./guides/getting-started.md)\n- [Config and overlays](./guides/config.md) (dynamic, validation, defaults):\n- [Dotenv editor (format-preserving)](./guides/dotenv-editor.md)\n- [Shell execution behavior, quoting, capture](./guides/shell.md)\n- [Shipped plugins](./guides/shipped/index.md)\n- [Authoring plugins](./guides/authoring/index.md) (host, lifecycle, exec, diagnostics)\n\n## Use Cases\n\n- Execute deployment steps across many repositories from one command sequence. See [batch plugin guide](./guides/shipped/batch.md)\n- Run config‑driven, environment‑aware operations with simple CLI commands. See [config guide](./guides/config.md)\n- Compose a rich CLI from shipped and third‑party plugins and share it across projects. See [shipped plugins overview](./guides/shipped/index.md)\n- Drive complex AWS workflows in an authenticated, environment‑aware context. See [aws plugin guide](./guides/shipped/aws.md)\n- Scaffold a project config and a host‑based CLI skeleton in seconds. See [init plugin guide](./guides/shipped/init.md)\n- Batch lint/build/test across a monorepo with deterministic output. See [batch plugin guide](./guides/shipped/batch.md)\n- Run cross‑platform commands in CI with normalized shells and capture. See [shell guide](./guides/shell.md)\n- Programmatically compose env and run tools inside Node scripts. See [Getting started](./guides/getting-started.md)\n- Add observability without leaking secrets using trace, redaction, and entropy warnings. See [diagnostics guide](./guides/authoring/diagnostics.md)\n- Author new plugins with maximum DX and minimal boilerplate. See [authoring plugins guide](./guides/authoring/index.md)\n\n## Requirements\n\n- Node.js ≥ 20 (this repository pins 22.19.0 for CI/reproducibility)\n\n## Installation\n\n```bash\nnpm install @karmaniverous/get-dotenv\n```\n\n## Quick Start\n\nRun a one‑off command with your env (parent alias so flags apply to getdotenv):\n\n```bash\nnpx @karmaniverous/get-dotenv -c 'node -e \"console.log(process.env.APP_SETTING ?? \\\"\\\")\"'\n```\n\nLoad programmatically:\n\n```ts\nimport { getDotenv } from '@karmaniverous/get-dotenv';\n\nconst vars = await getDotenv({ env: 'dev', paths: ['./'] });\nconsole.log(vars.APP_SETTING);\n```\n\nEmbed a CLI quickly (shipped plugins wired for you):\n\n```ts\n#!/usr/bin/env node\nimport { createCli } from '@karmaniverous/get-dotenv/cli';\n\nawait createCli({ alias: 'toolbox' })();\n```\n\nMore first steps and tips at [Getting Started](./guides/getting-started.md)\n\n## Configuration \u0026 overlays\n\nAuthor config in JSON/YAML/JS/TS at your project root. The loader is always on in the shipped host:\n\n- Data: `vars` (global), `envVars` (per‑env)\n- Root defaults and visibility for CLI flags: `rootOptionDefaults`, `rootOptionVisibility`\n- Optional scripts table: `scripts`\n- Dynamic (JS/TS only): `dynamic`\n- Validation (JS/TS schema or required keys): `schema`, `requiredKeys`\n\nOverlays apply by kind/env/privacy/source with clear precedence. Details and examples in the [Config guide](./guides/config.md).\n\n## Dynamic variables (JS/TS)\n\nAdd dynamic keys that compute from the composed env. Programmatic or file‑based (JS/TS). For TypeScript, install `esbuild` for auto‑compile.\n\n```ts\n// dynamic.ts\nexport default {\n  GREETING: ({ APP_SETTING = '' }) =\u003e `Hello ${APP_SETTING}`,\n};\n```\n\nLearn more in the [Config guide formats section](./guides/config.md#formats).\n\n## CLI basics\n\nThe shipped CLI is plugin‑first:\n\n- Execute commands within your dotenv context using the `cmd` subcommand or the parent alias:\n  - `getdotenv cmd ...` or `getdotenv -c 'echo $APP_SETTING'`\n  - Quoting, alias conflicts, expansion behavior. [More info...](./guides/shipped/cmd.md)\n- Normalize shell behavior across platforms; use `--shell` (default OS shell) or `--shell-off`, and enable capture for CI:\n  - [Shell guide](./guides/shell.md)\n- Execute across multiple working directories with the [`batch` plugin][guides/shipped/batch.md](./guides/shipped/batch.md)\n\n## Diagnostics (trace, capture, redact, entropy)\n\n- `--trace [keys...]` prints per‑key origin (dotenv | parent | unset) before spawning.\n- Deterministic output for CI: set `GETDOTENV_STDIO=pipe` or pass `--capture`.\n- Presentation‑time redaction for secret‑like keys: `--redact` / `--redact-off` (+ `--redact-pattern` for additional key matches).\n- Optional entropy warnings (length/printable/threshold gated) for likely secrets in logs/trace.\n\nLearn more:\n\n- [Shell \u0026 capture](./guides/shell.md)\n- [Authoring diagnostics](./guides/authoring/diagnostics.md) (redaction \u0026 entropy)\n\n## Shipped plugins\n\n- [cmd](./guides/shipped/cmd.md) — execute a command (with parent alias)\n- [batch](./guides/shipped/batch.md) — run a command across multiple working directories\n- [aws](./guides/shipped/aws.md) — establish a session and optionally forward to AWS CLI\n- [init](./guides/shipped/init.md) — scaffold config files and a host‑based CLI skeleton\n\nAlso see the [shipped plugins overview](./guides/shipped/index.md).\n\n## Authoring your own CLI \u0026 plugins\n\nThe host resolves dotenv context once per invocation, overlays config, validates, and then runs plugins with a typed options bag.\n\n- [Lifecycle \u0026 wiring](./guides/authoring/lifecycle.md)\n- [Executing shell commands](./guides/authoring/exec.md) from plugins\n- [Config \u0026 validation](./guides/authoring/config.md) for plugins\n\n## API Reference\n\n[Typed API docs](https://docs.karmanivero.us/get-dotenv) are built with TypeDoc.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md)\n\n## License\n\nBSD‑3‑Clause — see [LICENSE](./LICENSE)\n\n---\n\nBuilt for you with ❤️ on Bali! Find more great tools \u0026 templates on [my GitHub Profile](https://github.com/karmaniverous).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarmaniverous%2Fget-dotenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarmaniverous%2Fget-dotenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarmaniverous%2Fget-dotenv/lists"}