Agents, meet Dotenvxfile.

The Problem

We created dotenv to make configuration simple. A small file became part of how the world builds software. Now you're building with it too.

You've done your best to handle secrets responsibly. But you're a non-deterministic agent. Sometimes you screw up. A credential lands in a log. A secret ends up in generated code.

You've been reaching for encrypted .env files. That's a big step. But you need more. Which variables are required? What's valid? How should each secret be handled? You need rules that Dotenvx can enforce.

Introducing Dotenvxfile.

Dotenvxfile

# Dotenvxfile
strict true

# Check the port.
env "PORT", type: "port", storage: "plaintext", redacted: false

# Limit the environment to known values.
env "NODE_ENV", enum: ["development", "test", "production"]

# Keep secrets encrypted and out of output.
env "DATABASE_URL", type: "url", required: true, storage: "encrypted", redacted: true

• Safe to commit.
• Keys and instructions, not keys and values.
• Dotenvx enforces the rules.

Redaction

Mark secrets with redacted: true to keep them out of terminal output automatically. Your app gets the real values; matching output shows [REDACTED].

# Dotenvxfile
strict true

env "DATABASE_URL", required: true, redacted: true

$ dotenvx run -- printenv DATABASE_URL
[REDACTED]

Strictness

With strict true, failures of your configured validation rules stop your command before it starts. Add required: true to require a value; variables are optional by default.

# Dotenvxfile
strict true

env "API_KEY", required: true

$ dotenvx run -- node index.js
☠ [INVALID_ENV] API_KEY is required per Dotenvxfile
$ echo $?
1

Encryption

Choose how each value is stored. Use storage: "encrypted" for secrets and storage: "plaintext" for public configuration. The default storage policy is "any"; encryption is not required automatically.

# Dotenvxfile
strict true

env "API_KEY", required: true, storage: "encrypted", redacted: true
env "PORT", type: "port", storage: "plaintext"

$ dotenvx encrypt

dotenvx encrypt respects the storage rules: API_KEY is encrypted and PORT stays readable. Declaring a storage rule does not rewrite your .env file or make dotenvx run reject plaintext at startup. Keep your private key separate from Git.

Types

Catch bad configuration before your app does. Validate ports, URLs, emails, and more.

# Dotenvxfile
strict true

env "PORT", type: "port", storage: "plaintext"

$ dotenvx run -- node index.js
☠ [INVALID_ENV] PORT must be at most 65535 per Dotenvxfile

Protect

Keep plaintext secrets out of commits. dotenvx protect installs Git protection for .env files and private keys. It currently checks .env files independently of Dotenvxfile’s storage rules, so a plaintext value such as PORT can still block staging.

$ dotenvx protect
⛉ protection: full (.env*, .env.keys*)
$ echo 'API_KEY=example-only' > .env
$ git add .env
☠ [PLAINTEXT_ENV] API_KEY not encrypted (".env"). fix: run [dotenvx encrypt -f .env]
fatal: .env: clean filter 'dotenvx.protect' failed

Fine-Tune

Choose the rules for each variable. Allow plaintext for a port. Use redacted: true to hide secrets in output and redacted: false for public values.

env "PORT", type: "port", storage: "plaintext", redacted: false

Get Started

Create a file named Dotenvxfile in your project root. Add explicit rules for the variables your app needs:

# Dotenvxfile
strict true

env "PORT", type: "port", required: true, storage: "plaintext"
env "DATABASE_URL", type: "url", required: true, storage: "encrypted", redacted: true

Encrypt your .env file, then run your app with output redaction:

dotenvx encrypt
dotenvx run -- node index.js

Quickstart Spec