Environment variables have become the standard way to configure applications. Database credentials, API keys, third-party service tokens — they all live in `.env` files during development. But here's the problem: these plaintext files are a security liability.

If your `.env` file gets exposed — through a misconfigured server, a leaked backup, or a compromised developer machine — every secret inside is immediately compromised. And yet, we've been using them this way for over a decade.

**Dotenvx changes that.**

## What is Dotenvx?

Dotenvx is a secure evolution of the original `dotenv` library, created by the same author (Scott Motte). It adds encryption to your `.env` files, allowing you to safely commit them to version control while keeping your secrets protected.

The key innovation is cryptographic separation: your encrypted secrets live in your codebase, but the decryption key is stored separately. An attacker would need both to access your secrets.

## Why Encryption Matters

Consider what happens in a typical breach scenario with plaintext `.env` files versus encrypted ones:

**Git repository exposed** — With plaintext files, all secrets are immediately leaked. With dotenvx, attackers get an encrypted blob that's useless without the separate decryption key.

**Server compromise** — Plaintext secrets are readable the moment an attacker gains access. With dotenvx, they'd also need access to wherever you store the private key (typically a different system entirely).

**CI/CD breach** — If your CI/CD platform is compromised, plaintext environment variables stored there are stolen directly. With dotenvx, only the encrypted files exist in your codebase.

**Backup leak** — Database dumps, server snapshots, or repository backups containing plaintext `.env` files expose everything. Encrypted files remain protected.

The CircleCI breach in early 2023 is a perfect example. Attackers accessed environment variables stored in the CI/CD platform but couldn't access codebases. With dotenvx, even if they had accessed both, the encrypted `.env` files would have been useless without the private decryption keys stored elsewhere.

## How Dotenvx Works

Dotenvx uses Elliptic Curve Integrated Encryption Scheme (ECIES) with AES-256 encryption. Here's the simplified flow:

1.  **Initialization**: When you encrypt a `.env` file, dotenvx generates a key pair:
    
    -   `DOTENV_PUBLIC_KEY` — used to encrypt secrets (safe to commit)
    -   `DOTENV_PRIVATE_KEY` — used to decrypt secrets (never commit)
2.  **Encryption**: Each secret value is encrypted individually using a unique ephemeral key, then that key is encrypted with the public key.
    
3.  **Decryption**: At runtime, dotenvx uses the private key to decrypt secrets and inject them as environment variables.
    

### Installation

```bash
# macOS/Linux
curl -sfS https://dotenvx.sh/install.sh | sh

# Or via npm
npm install @dotenvx/dotenvx --save

# Or via Homebrew
brew install dotenvx/brew/dotenvx
```

### Basic Usage

**Step 1: Create your `.env` file**

```bash
echo "DATABASE_URL=postgres://user:password@localhost/myapp" > .env
echo "API_SECRET=sk_live_abc123xyz" >> .env
```

**Step 2: Encrypt it**

```bash
dotenvx encrypt
```

Your `.env` file now looks like this:

```bash
#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
#/ public-key encryption for .env files                    /
#/----------------------------------------------------------/
DOTENV_PUBLIC_KEY="02a5c9..."

DATABASE_URL="encrypted:BGVh3..."
API_SECRET="encrypted:BKrt5..."
```

And a new `.env.keys` file is created:

```bash
#/------------------!DOTENV_PRIVATE_KEYS!-------------------/
#/ private decryption keys. DO NOT commit to source control /
#/----------------------------------------------------------/
DOTENV_PRIVATE_KEY="a1b2c3d4..."
```

**Step 3: Add `.env.keys` to `.gitignore`**

```bash
echo ".env.keys" >> .gitignore
```

**Step 4: Commit your encrypted `.env`**

```bash
git add .env
git commit -m "Add encrypted environment configuration"
```

**Step 5: Run your application**

```bash
# Locally (dotenvx reads from .env.keys automatically)
dotenvx run -- node app.js

# In production (set the private key as an env var)
DOTENV_PRIVATE_KEY="a1b2c3d4..." dotenvx run -- node app.js
```

## Multiple Environments

Dotenvx supports environment-specific files with a naming convention:

```bash
.env                    # Default/development
.env.staging            # Staging environment  
.env.production         # Production environment
.env.ci                 # CI/CD pipelines
```

Each file gets its own key pair:

```bash
dotenvx encrypt -f .env.production
dotenvx encrypt -f .env.staging
```

Your `.env.keys` will contain multiple keys:

```bash
DOTENV_PRIVATE_KEY="..."
DOTENV_PRIVATE_KEY_STAGING="..."
DOTENV_PRIVATE_KEY_PRODUCTION="..."
```

At runtime, the key suffix determines which file to decrypt:

```bash
# Decrypts .env.production
DOTENV_PRIVATE_KEY_PRODUCTION="..." dotenvx run -- php artisan serve

# Decrypts both .env and .env.production (production values override)
DOTENV_PRIVATE_KEY="..." DOTENV_PRIVATE_KEY_PRODUCTION="..." dotenvx run -- php artisan serve
```

## Language Support

Dotenvx works as a CLI wrapper, so it's language-agnostic:

```bash
# Node.js
dotenvx run -- node app.js

# Python
dotenvx run -- python main.py

# Ruby
dotenvx run -- bundle exec rails server

# PHP
dotenvx run -- php artisan serve

# Go
dotenvx run -- go run main.go

# Any command
dotenvx run -- ./your-binary
```

## Key Security Practices

1.  **Never commit `.env.keys`** — Add it to `.gitignore` immediately
2.  **Store private keys in your deployment platform** — Use your hosting provider's secrets management
3.  **Rotate keys periodically** — Generate new keys and re-encrypt when team members leave
4.  **Use environment-specific keys** — Don't use the same private key across all environments
5.  **Limit key access** — Only production servers should have production keys

## When to Use Dotenvx

Dotenvx is ideal when:

-   You want encrypted secrets in version control
-   Multiple developers need access to the same configuration
-   You deploy to multiple environments (staging, production, etc.)
-   You want to avoid third-party secrets management services
-   You need a simple, auditable secrets workflow

It's a straightforward upgrade from plaintext `.env` files that dramatically reduces your attack surface without adding operational complexity.

----------

_Dotenvx is open source and free to use. For team features like syncing, access controls, and audit logs, see [Dotenvx Ops](https://dotenvx.com/ops)._