dotenvx

dotenvx is a secure, cross-platform successor to the original dotenv library, built by the same author (Scott Motte). It extends the familiar .env file convention with public-key encryption, letting teams commit encrypted secrets straight to version control and decrypt them only at runtime via a companion .env.keys file. Beyond the drop-in require('@dotenvx/dotenvx').config() API, it ships as a standalone CLI (dotenvx / dx) that wraps any command — dotenvx run -- node index.js, dotenvx run -- python3 app.py, dotenvx run -- cargo run — injecting decrypted environment variables into the child process regardless of language or framework.

Beyond core encryption, dotenvx layers on multi-environment support (.env.production, .env.staging), value redaction for safely piping secrets through AI coding agents, native OS keychain plus 1Password/Bitwarden secret-reference resolution, .env.example validation, and monorepo-aware resolution of the nearest .env file per package. It installs via npm, Homebrew, curl, winget, Docker, or as a standalone binary, making it usable in virtually any deployment pipeline without a language-specific SDK.

What You Get

• A drop-in replacement for dotenv — require('@dotenvx/dotenvx').config() or import '@dotenvx/dotenvx/config'
• Public-key encryption for .env files, so ciphertext can be committed to git safely
• A dotenvx run -- wrapper that injects decrypted env vars into any command, in any language
• Native installers for npm, Homebrew, curl, winget, and Docker, plus a standalone compiled binary
• Multi-environment file conventions (.env.production, .env.ci, etc.) resolved automatically
• Secret redaction (--redact) for piping real secrets through AI coding agents like Claude Code and Codex without leaking them in output

Common Use Cases

• Committing encrypted environment secrets directly into a git repo without a separate secrets manager
• Running the same app across dev/staging/production .env files without changing code
• Injecting decrypted secrets into a non-Node.js process — Python, Ruby, Go, Rust, PHP, Java — via the CLI wrapper
• Letting an AI coding agent run commands against real API keys while redacting them from the transcript
• Resolving secrets from 1Password, Bitwarden, or the OS keychain instead of a plaintext .env file

Under The Hood

Architecture The CLI entry point (src/cli/dotenvx.js) builds a Commander-style program that registers one subcommand per action (run, get, set, del, encrypt, decrypt, ls, keypair, login, logout, settings, ext, lock, armor), and each command delegates immediately to a same-named file under src/cli/actions/, keeping the CLI layer a thin argument-parsing shell over the real logic. Core value resolution lives in src/lib/main.js, which composes resolvers/ (reading and decrypting env values), providers/ and decryptors/ (pulling keys from the OS keychain, 1Password, Bitwarden, or dotenvx’s own Armor cloud service), and transforms/set.js (writing values back). A Session class centralizes per-invocation state, and the layering means swapping a key-resolution strategy never touches the CLI or encryption code — a genuinely modular provider-pattern architecture.

Tech Stack Written in plain JavaScript (no TypeScript source) with hand-authored .d.ts declarations for consumers. Core dependencies are its own @dotenvx/primitives (encryption/parsing) and @dotenvx/tooling (CLI framework plus sync-worker helpers), with yocto-spinner for CLI progress. Standalone binaries are built with esbuild and @yao-pkg/pkg, releases are automated with standard-version, and install paths span npm, a Homebrew tap, a curl installer, winget, a Docker image, and compiled GitHub Releases binaries — an unusually wide distribution matrix for an npm package.

Code Quality Tests run on tap with sinon for stubbing and proxyquire for dependency injection, plus a separate shellspec-based suite for CLI-level black-box tests; 117 test files cover tests/cli, tests/lib, tests/db, and tests/e2e, with fixtures for edge cases like UTF-16LE encoding, multiline values, and monorepo layouts. Linting is enforced via the zero-config standard preset, and release:check runs both suites before every release. Error handling goes through a centralized Errors helper for consistent, coded output rather than ad hoc throws.

API Design What sets dotenvx apart from dotenv, direnv, or a typical secrets manager is treating the .env file itself as the encrypted artifact — public-key encryption lets ciphertext live in git with no external secrets service required, and the dotenvx run -- wrapper makes secret injection language-agnostic instead of tying it to Node’s require(). The --redact flag is a genuinely novel addition aimed at the AI-agent era, letting an LLM CLI run with real credentials while scrubbing them from anything it prints. Combined with pluggable external secret providers resolved through the same interface as its own encryption, dotenvx reads as an actively evolving take on env-var management rather than a simple dotenv fork.