# @calvear/env > Extensible environment variables handler for NodeJS apps Latest version **3.4.2** (published 2026-09-08) · MIT license · 0 weekly downloads ## Install ```sh npm install @calvear/env pnpm add @calvear/env yarn add @calvear/env bun add @calvear/env ``` Provides the command `env`. ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 3.4.2 | | Published | 2026-09-08 | | First published | 2022-04-05 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=20 | | Dependencies | 9 | | Unpacked size | 210.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Author | Alvear Candia, Cristopher Alejandro | | Maintainers | calvear | | Keywords | env, node, cli, typescript | ## Links - npm: https://www.npmjs.com/package/@calvear/env - Repository: https://github.com/calvear93/env - Homepage: https://github.com/calvear93/env#readme - Issues: https://github.com/calvear93/env/issues - npm.io page: https://npm.io/package/@calvear/env ## Dependencies (9) - [ajv](https://npm.io/package/ajv.md) ^8.20.0 - [tslog](https://npm.io/package/tslog.md) ^4.10.2 - [yargs](https://npm.io/package/yargs.md) ^18.0.0 - [ci-info](https://npm.io/package/ci-info.md) ^4.4.0 - [subslate](https://npm.io/package/subslate.md) ^1.0.0 - [merge-deep](https://npm.io/package/merge-deep.md) ^3.0.3 - [picocolors](https://npm.io/package/picocolors.md) ^1.1.1 - [ajv-formats](https://npm.io/package/ajv-formats.md) ^3.0.1 - [to-json-schema](https://npm.io/package/to-json-schema.md) ^0.2.5 ## Alternatives - [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads - [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads - [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads - [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads - [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads ## Recent versions - 3.4.2 (latest) — 2026-09-08 - 3.4.1 — 2026-07-17 - 3.4.0 — 2026-07-08 - 3.2.0 — 2026-07-02 - 3.1.1 — 2026-06-24 - 3.1.0 — 2026-06-02 - 3.0.1 — 2026-05-31 - 3.0.0 — 2026-05-31 - 2.10.6 — 2025-11-15 - 2.10.5 — 2025-10-10 - 2.10.4 — 2025-10-10 - 2.10.3 — 2024-04-26 - 2.10.2 — 2024-02-12 - 2.10.1 — 2024-02-03 - 2.9.2 — 2023-12-28 - … 22 more at https://npm.io/package/@calvear/env/versions ## README
@calvear/env logo

env

Environment variables made easy — load, validate, inject.

version   esm   typescript   node engine   coverage   license


## 📖 About `@calvear/env` eases **environment variable handling** for NodeJS apps — like [env-cmd](https://www.npmjs.com/package/env-cmd) or [dotenv](https://www.npmjs.com/package/dotenv), but with **powerful, extensible features**: pluggable **providers** to `load`, `pull` and `push` variables from different stores, **JSON Schema validation**, value **interpolation**, secret **masking** and nested/shared keys. ### ✨ Features - 🧩 **Provider plugins** — bundled `package-json`, `app-settings`, `secrets` and `local` providers, plus your own (NPM package or local script). - 💉 **Injection** — load variables into `process.env` and run any command. - ✅ **JSON Schema** — auto-generate and validate variables before injecting. - 🪆 **Nested & global keys** — `GROUP__VAR` flattening and `$`-prefixed global keys (the `$` marker is stripped on injection). - 🧵 **Interpolation** — reference other args/vars with `[[ ]]` delimiters. - 🙈 **Masking** — hide secrets in the debug output by key name, key regex, or value content regex. - 🎨 **Pretty output** — colorized, sorted, masked debug render of the resolved environment. - 📤 **Export** — write the unified environment to a `.env` or JSON file.

(back to top)

## 📌 Requirements [NodeJS](https://nodejs.org/) **20 or higher**. ```bash > node -v v20.0.0 ```

(back to top)

## 📦 ESM only Since **v3** this package is **ESM-only** (`"type": "module"`). Consumers must use ESM `import` syntax, and custom providers must be ESM modules that `export` their provider object. ```javascript // ✅ ESM import { EnvProvider } from '@calvear/env'; // ❌ CommonJS require is not supported // const { EnvProvider } = require('@calvear/env'); ```

(back to top)

## ⚡️ Quick start Install the package: ```bash > npm install @calvear/env ``` Run the binary directly: ```bash > npx env --help Usage: env [command] [options..] [: subcmd [:]] [options..] Commands: env [options..] [: :] env pull [options..] env push [options..] env schema [options..] env export [options..] ``` Or wire it into your **npm scripts**: ```jsonc { "scripts": { // inject "dev" variables (debug mode) and start the app "start:dev": "env -e dev -m debug : node dist/main.js", // inject "prod" variables for the build "build:prod": "env -e prod -m build : tsc", // regenerate the validation schema "env:schema": "env schema -e dev", }, } ``` Run it: ```bash > npm run start:dev ⚡ env v3.0.0 · 🌎 dev · 🧩 debug 📦 package-json 6 vars 🗂️ app-settings 5 vars 🔐 secrets 1 secrets 📂 local 1 vars environment (12 variables) ENV = dev NODE_ENV = development SECRET = ***** VERSION = 3.0.0 ... ✓ 12 variables loaded in 142ms ▶ node dist/main.js My environment loaded is: dev ✓ finished in 168ms ``` > The resolved environment is only rendered at `--log debug`. Values are > **sorted**, **secrets are masked**, and colored by type — strings in gray, > numbers in orange, booleans `true`/`false` in green/red.

(back to top)

## ⚙️ Commands & Options > **Interpolation** — any option value can reference other arguments using `[[` > and `]]` delimiters. With `root: "config"`, the value `[[root]]/file.json` > resolves to `config/file.json`; with `env: "dev"`, > `[[root]]/config.[[env]].json` resolves to `config/config.dev.json`. ### Global options | Option | Description | Type | Default | | ---------------------------------- | ------------------------------------------------- | ---------- | ------- | | `--help` | Show help | `boolean` | | | `-e, --env` | Environment to load (i.e. `dev`, `prod`) | `string` | | | `-m, --modes` | Execution modes (i.e. `debug`, `test`) | `string[]` | `[]` | | `--nd, --nestingDelimiter` | Nesting-level delimiter for flatten | `string` | `__` | | `--arrDesc, --arrayDescomposition` | Serialize (`false`) or break down (`true`) arrays | `boolean` | `false` | | `-x, --expand` | Interpolate environment variables using itself | `boolean` | `false` | | `--ci` | Continuous Integration mode (skips local files) | `boolean` | auto | ### Workspace options | Option | Description | Type | Default | | ---------------------- | --------------------------------- | -------- | --------------------------------- | | `--root` | Base environment folder path | `string` | `env` | | `-c, --configFile` | Config JSON file path | `string` | `[[root]]/settings/settings.json` | | `-s, --schemaFile` | Environment schema JSON file path | `string` | `[[root]]/settings/schema.json` | | `--pkg, --packageJson` | `package.json` path | `string` | _cwd_ | ### JSON Schema options | Option | Description | Type | Default | | ---------------------- | ---------------------------------------------- | ------------------ | ------- | | `-r, --resolve` | Merge new schema or override it | `merge`/`override` | `merge` | | `--null, --nullable` | Whether variables are nullable by default | `boolean` | `true` | | `--df, --detectFormat` | Include string formats in the generated schema | `boolean` | `false` | ### Logger options | Option | Description | Type | Default | | ------------------------------ | ------------------------------------------------------ | --------------------------------------------- | ------- | | `--log, --logLevel` | Log level | `silly`/`trace`/`debug`/`info`/`warn`/`error` | `info` | | `--mvk, --logMaskValuesOfKeys` | Mask a value when its **key** matches (exact or regex) | `string[]` | `[]` | | `--mrx, --logMaskAnyRegEx` | Mask **value content** matching a regex (every match) | `string[]` | `[]` | See [🙈 Masking secrets](#-masking-secrets) for the full masking semantics. ### 🔮 Environment inference from npm scripts When `-e` is not provided (neither by CLI nor config file), the CLI infers the environment from the **npm script name** (`npm_lifecycle_event`), taking the last segment after `:` — running `npm run start:dev` infers `dev`, so the `-e` flag becomes redundant in per-env scripts: ```jsonc { "scripts": { "start:dev": "env -m debug : node dist/main.js", // infers "dev" "start:qa": "env -m debug : node dist/main.js", // infers "qa" "start:prod": "env -m debug : node dist/main.js", // infers "prod" }, } ``` The inferred value is validated against the environments **defined** in the workspace, discovered dynamically as the union of: - the `|ENV|` and `|LOCAL|` section keys of `appsettings.json`, - per-env provider files in the root folder (`appsettings..json`, `appsettings..local.json`, `.env.json`, `.local.env.json`). Validation rules: - **inferred** env unknown → the command **aborts** listing the defined environments (catches typos like `start:prd`); - **explicit** `-e` unknown → only a **warning**; - no defined environments → inference is skipped silently; - scripts without a `:` suffix (i.e. `preview`) and direct CLI invocations are unaffected. Scripts whose suffix is **not** an environment (i.e. `test:mutation`, `env:schema`) must keep an explicit `-e`. > `[[env]]` inside `--configFile` cannot reference an inferred environment — > the config file is loaded **before** inference runs. --- ### `env` Inject environment variables into `process.env` and execute a command (the command goes after `:`). ```bash env -e [options..] [: :] [options..] ``` ```bash > env -e dev -m test unit : npm test > env -e dev -m debug : npm start : -c [[root]]/[[env]].env.json > env -e prod -m build optimize : npm run build ``` | Option | Description | Type | Default | | ------------------------------ | ------------------------------------------ | --------- | ------- | | `--validate, --schemaValidate` | Validate variables against the JSON schema | `boolean` | `true` | ### `pull` Pull environment variables from the providers' stores (for providers that implement `pull`, i.e. custom remote providers). ```bash env pull -e [options..] ``` | Option | Description | Type | Default | | ----------------- | ------------------------- | --------- | ------- | | `-o, --overwrite` | Overwrite local variables | `boolean` | `false` | ### `push` Push environment variables to the providers' stores (for providers that implement `push`). ```bash env push -e [options..] ``` | Option | Description | Type | Default | | ------------- | ---------------------- | --------- | ------- | | `-f, --force` | Force push for secrets | `boolean` | `false` | ### `schema` Generate (or update) the validation schema from the providers' output. ```bash > env schema -e dev -m build ``` ### `export` Export the unified environment to a file. ```bash env export -e -m [options..] ``` | Option | Description | Type | Default | | --------------- | --------------------- | --------------- | -------- | | `-u, -p, --uri` | Output file path | `string` | `.env` | | `-f, --format` | Output format | `dotenv`/`json` | `dotenv` | | `-q, --quotes` | Wrap values in quotes | `boolean` | `false` | ```bash > env export -e dev -m build -f json --uri [[env]].env.json ```

(back to top)

## 📡 Providers Providers are the core of this library. It ships with **four integrated providers**, and you can add your own. ### `package-json` Loads project info from your `package.json` (`version`, `project`, `name`, `title`, `description`) into `ENV`, `VERSION`, `PROJECT`, `NAME`, `TITLE`, `DESCRIPTION`. | Option | Description | Type | Default | | ------------------- | ------------------------------- | -------- | ------- | | `--vp, --varPrefix` | Prefix for the loaded variables | `string` | `""` | ```bash # i.e. expose them as REACT_APP_* for CRA > env -e dev -m build : react-scripts build : --vp REACT_APP_ ``` ### `app-settings` Non-secret loader for `appsettings.json`, organized by sections: ```jsonc { "|DEFAULT|": { "VAR1": "v1_default" }, "|ENV|": { "dev": { "C1": "V1", "GROUP1": { "VAR2": "G1V2", "GROUP2": { "VAR1": "G1G2V1" } }, }, }, "|MODE|": { "build": { "NODE_ENV": "production" }, "debug": { "NODE_ENV": "development" }, }, "|LOCAL|": { "dev": { "LOCAL_VAR": "only-local" } }, } ``` It also merges the unitary files `appsettings..json`, `appsettings..json` and `appsettings..local.json`. #### Precedence (lowest → highest) 1. flat root object (only when no `|...|` section is present) 2. `|DEFAULT|` 3. `|ENV|` for the current `--env` 4. `|MODE|` for each `--modes` entry (later modes win) 5. `appsettings..json` 6. `appsettings..json` (one per mode, in `--modes` order) 7. `|LOCAL|` for the current `--env` 8. `appsettings..local.json` Local layers (7 and 8) always win, and both are skipped in `--ci`. | Option | Description | Type | Default | | ----------------- | ----------------------------- | -------- | --------------------------- | | `--ef, --envFile` | Non-secret settings file path | `string` | `[[root]]/appsettings.json` | ### `secrets` Loads secret variables from a per-environment JSON file (`[[root]]/[[env]].env.json`). Keep this file out of version control. | Option | Description | Type | Default | | --------------------- | -------------------------- | -------- | --------------------------- | | `--sf, --secretsFile` | Secret variables file path | `string` | `[[root]]/[[env]].env.json` | ### `local` Loads local-only variables (never loaded in `--ci`). The file is auto-created if missing. | Option | Description | Type | Default | | ------------------- | ------------------------- | -------- | --------------------------------- | | `--lf, --localFile` | Local variables file path | `string` | `[[root]]/[[env]].local.env.json` |

(back to top)

## ✒️ Creating custom providers Create a provider in two ways: - **Local script** — a `.js` file that `export default`s your provider. - **NPM package** — a published module that `export default`s your provider. Both are wired in the [config file](#-config) via the `providers` list. A custom provider can also implement `pull`/`push` to fetch and publish variables from a remote store (i.e. a vault, a secrets manager or an API). ```typescript import type { CommandArguments, EnvProvider } from '@calvear/env'; import { logger, readJson, writeJson } from '@calvear/env/utils'; const KEY = 'my-unique-provider-key'; interface MyProviderArguments extends CommandArguments { anyExtraOption: boolean; } const MyProvider: EnvProvider = { // unique identifier key: KEY, // (optional) add custom options to the CLI via yargs builder: (builder) => { builder.options({ anyExtraOption: { group: KEY, alias: ['a', 'aeo'], type: 'boolean', default: false, describe: 'Any option description', }, }); }, // called on load — may be sync or async, and may return a list to merge load: ({ env }) => { if (env === 'dev') return { NODE_ENV: 'development' }; return [{ NODE_ENV: 'production' }, { ANY_GROUP: { INNER_VAR: 12 } }]; }, // (optional) called on `env pull` pull: (argv, config) => { /* fetch variables into your local cache */ }, // (optional) called on `env push` push: (argv, config) => { /* publish/update your variables */ }, }; export default MyProvider; ```

(back to top)

## 📥 Config Any CLI argument can be set in your config file (`[[root]]/settings/settings.json` by default), but it is mainly used to declare **providers**: ```jsonc { "logLevel": "silly", // mask secrets in the debug output (see the Masking section) "logMaskValuesOfKeys": ["SECRET", "/token/i", "/api_key/i"], "logMaskAnyRegEx": ["AKIA[0-9A-Z]{16}"], "providers": [ { "path": "package-json" }, { "path": "app-settings" }, { "path": "secrets" }, { "path": "local" }, // custom NPM package { "path": "@my-scope/my-provider", "type": "module", "config": {} }, // custom local script { "path": "scripts/custom-loader.js", "type": "script" }, ], } ``` > **Provider order matters** — providers are merged in declaration order, so > later providers override earlier ones (`package-json` is the base, `local` > wins).

(back to top)

## 🪆 Nested & global keys Organize variables in nested objects. They are **flattened** into `process.env` using the nesting delimiter (`__` by default): ```jsonc { "GROUP1": { "VAR": "anyValue1", "GROUP2": { "VAR": "anyValue2" }, }, "VAR3": "anyValue3", } ``` ```javascript process.env.GROUP1__VAR; // "anyValue1" process.env.GROUP1__GROUP2__VAR; // "anyValue2" process.env.VAR3; // "anyValue3" ``` ### `$` global marker Prefix a key with `$` to mark it as **global/shared** — relevant for the `secrets` provider, which uses the marker to scope the secret across the project rather than per-mode. The marker is **stripped on injection** at any nesting depth, while the group prefix is **kept**: ```jsonc { "$TOKEN": "rootValue", "GROUP1": { "$SHARED": "groupValue", "VAR": "anyValue", }, } ``` ```javascript // the `$` is removed; the nesting prefix is preserved process.env.TOKEN; // "rootValue" (was $TOKEN) process.env.GROUP1__SHARED; // "groupValue" (was GROUP1.$SHARED) process.env.GROUP1__VAR; // "anyValue" ``` > The `$` is removed only from the **process environment** and from JSON Schema > validation keys. It is **preserved** in the secrets file storage, so the > `secrets` provider round-trips the global marker intact. > > Skip a key entirely (never injected) by prefixing it with `#`. ### Priority (lowest → highest) Providers are merged in declaration order — with the default `providers` list: 1. `NODE_ENV=development` (built-in base value) 2. `package-json` info 3. `appsettings.json` (`app-settings` — see the [app-settings precedence](#precedence-lowest--highest) above) 4. `.env.json` (`secrets`) 5. `.local.env.json` (`local`, skipped in `--ci` — overrides everything) > The resolved variables are written into the child process `process.env`, so > they override any variables inherited from the parent shell.

(back to top)

## 🙈 Masking secrets When the resolved environment is rendered (at `--log debug`) and when objects are logged, secrets are masked as `*****`. There are two complementary mechanisms, configurable via CLI flags or the [config file](#-config): ### By key — `logMaskValuesOfKeys` (`--mvk`) Masks a variable's **whole value** when its **key** matches. Each entry is either an **exact key name** (case-insensitive) or a `/source/flags` **regex** matched against the key: ```jsonc { "logMaskValuesOfKeys": [ "PASSWORD", // exact key (case-insensitive) "/token/i", // any key containing "token" "/_secret$/i", // any key ending in "_secret" ], } ``` ```bash # same, via CLI flag > env -e dev --log debug --mvk PASSWORD "/token/i" : node app.js ``` ### By value content — `logMaskAnyRegEx` (`--mrx`) Masks **only the matching portion** of any string value, wherever it appears. The global flag is always forced, so **every** occurrence is masked; use the `/source/flags` form for extra flags such as `i`: ```jsonc { "logMaskAnyRegEx": [ "AKIA[0-9A-Z]{16}", // AWS access key ids "/bearer .+/i", // bearer tokens (case-insensitive) ], } ``` | Goal | Use | | --------------------------------------------------- | --------------------- | | Know the **key** of the secret | `logMaskValuesOfKeys` | | Know the **shape** of the secret (token, key, RUT…) | `logMaskAnyRegEx` | > In JSON the backslash must be escaped: write `\\d` for `\d`. Neither mechanism > masks the variable **name** — keys are always shown. Masking only affects the > output; the real (unmasked) values are still injected into `process.env`.

(back to top)

## 🧰 Development scripts | Script | Description | | -------------------- | ------------------------------------------------- | | `pnpm build` | Build the library (Vite, ESM) into `dist/` | | `pnpm test` | Run unit tests (Vitest) | | `pnpm test:cov` | Run unit tests with coverage (100% threshold) | | `pnpm test:int` | Run integration tests against the built binary | | `pnpm typecheck` | Type-check with `tsc --noEmit` | | `pnpm lint` | Lint with ESLint (flat config) | | `pnpm format` | Format with Prettier | | `pnpm run pub` | Gate + build + publish to npm (`latest`) | | `pnpm run pub:alpha` | Gate + build + publish a prerelease (`alpha` tag) |

(back to top)

## 🛠️ Built with - [yargs](http://yargs.js.org/) — CLI argument parsing - [ajv](https://ajv.js.org/) + [to-json-schema](https://www.npmjs.com/package/to-json-schema) — JSON Schema - [tslog](https://tslog.js.org/#/) — logging - [picocolors](https://github.com/alexeyraspopov/picocolors) — terminal colors - [subslate](https://github.com/josh-hemphill/subslate) — interpolation - [merge-deep](https://github.com/jonschlinkert/merge-deep) — deep merge - [Vite](https://vite.dev/) — build · [Vitest](https://vitest.dev/) — testing

(back to top)

## 📄 License This project is licensed under the **MIT License** — see [LICENSE.md](LICENSE.md) for details.

(back to top)

---

⌨ with ❤️ by Alvear Candia, Cristopher Alejandro

--- _Source: https://npm.io/package/@calvear/env · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._