dotenv-cli

dotenv-cli is a small command-line utility that loads environment variables from one or more .env files and then executes a given command with those variables applied to its environment. It solves a practical cross-platform problem: the VARIABLE=value command syntax used on Unix shells doesn’t work on Windows, so dotenv-cli sidesteps that entirely by loading variables into a spawned child process itself.

Beyond basic .env loading, it supports multiple -e file paths (first file wins on conflicting keys), cascading environment-specific files via -c (.env, .env.local, .env.<environment>, .env.<environment>.local), inline variable overrides via -v, variable expansion (via dotenv-expand) with an opt-out flag, and an override mode that lets .env values take priority over already-set system variables.

What You Get

• Cross-platform env loading that works the same in Bash, PowerShell, and CMD, unlike the VAR=value command shell syntax.
• Multiple .env file support via repeated -e flags, with first-file-wins precedence on conflicting keys.
• Cascading environment files (-c) that mimic the .env / .env.local / .env.<environment> / .env.<environment>.local pattern used by frameworks like Create React App.
• Inline variable injection via -v name=value, which takes precedence over file-based values.
• Variable expansion (via dotenv-expand) so values like APP_URL=http://${IP}:${PORT} resolve automatically, with a —no-expand escape hatch.

Common Use Cases

• Running an npm script with test-specific environment variables loaded from .env.test.
• Injecting secrets into a build or deploy command without needing native shell env-var syntax.
• Printing a single resolved environment variable value for use in shell scripting via -p.
• Loading a custom-named env file (e.g. .env.staging) into a Maven or other non-Node build command.

Under The Hood

Architecture

dotenv-cli is implemented as a single ~130-line script (cli.js) with no internal module boundaries: argument parsing (via minimist), path/cascade resolution, dotenv loading, variable expansion, and child-process spawning all happen sequentially in one file. Execution flows linearly from parsing process.argv, through building a list of candidate .env paths (adjusted for the -c cascade flag), to calling dotenv.config() per path, running dotenv-expand, merging in -v overrides, and finally spawning the target command via cross-spawn with stdio: 'inherit' and explicit forwarding of process signals (SIGINT, SIGTERM, etc.) to the child. There is no abstraction layer to change if the core behavior shifts — the whole tool is one procedural script, appropriate for its scope but with no separation of concerns.

Tech Stack

The tool targets Node.js and ships as a single npm bin entry (dotenv). Its runtime dependencies are minimal and current: dotenv (^17.1.0) for .env parsing, dotenv-expand (^12.0.0) for ${VAR} interpolation, cross-spawn (^7.0.6) for cross-platform child-process spawning, and minimist (^1.2.6) for flag parsing. The only dev dependency is the standard linter (v16) for style enforcement; there is no bundler, transpiler, or TypeScript — the source is plain CommonJS require()-based JavaScript distributed as-is via npm and Yarn.

Code Quality

No test files or test framework exist anywhere in the repository, and there is no CI configuration checked into the repo. Code style is enforced only via the standard linter (npm run lint), which mandates a consistent formatting convention but does not substitute for behavioral tests. Error handling is present but minimal: invalid -v arguments and conflicting -c/-o flags print a message and call process.exit(1), and child-process exit codes/signals are explicitly propagated. There is no static typing (plain JavaScript, no JSDoc types or TypeScript), so correctness relies entirely on manual testing and the small surface area of the script.

API Design The CLI surface is compact and mirrors common dotenv conventions users already know from other tools (-e, -c, -v, -p, --no-expand, -o/--override), keeping the learning curve low for anyone familiar with .env-file conventions. The -- separator convention for passing flags through to the wrapped command is a deliberate, well-documented affordance that avoids the tool’s own argument parser swallowing flags meant for the child process. Getting started requires zero configuration beyond installing the package and optionally creating a .env file — there is no setup boilerplate.