🔐 DotenvPP

Dotenv, but evolved. Environment configuration for the modern era.

Phase 1 ships interpolation and layered loading in Rust.

Why? • Features • Quick Start • What's Different • Architecture • Roadmap • Contributing

---

Why?

The .env file format was created in 2012. Since then:

• Cloud-native computing was born
• Supply chain attacks became the #1 threat vector
• Microservices replaced monoliths
• Edge computing and WASM emerged
• AI-assisted development changed how we write code

Yet .env files haven't changed at all. They're still plaintext, untyped, unvalidated, and insecure.

DotenvPP reimagines environment configuration from first principles — taking everything we've learned in 14 years and building something that actually helps instead of being a silent source of bugs and security vulnerabilities.

💡 A million secrets have been leaked from exposed .env files (Trend Micro, 2022). It's time for something better.

---

Features

DotenvPP 0.0.3 ships the parser foundation plus Phase 1 interpolation and layered loading.

Capability	Status	Notes
Basic KEY=VALUE parsing	✅ Shipped	Core parser behavior
Comments, blank lines, export	✅ Shipped	Common dotenv syntax
Single-quoted, double-quoted, and unquoted values	✅ Shipped	Includes multiline quoted values
BOM handling and common escape decoding	✅ Shipped	Phase 0 parser behavior
Load parsed values into std::env	✅ Shipped	Includes layered loading and override variants
CLI check and run commands	✅ Shipped	Supports --file and --env
Variable interpolation (${VAR})	✅ Shipped	Includes default, required, alternative, and $$ escaping
Environment layering	✅ Shipped	.env < .env.{ENV} < .env.local < .env.{ENV}.local
Schema and type system	⏳ Phase 2	Roadmap
Encryption	⏳ Phase 3	Roadmap
Expression language	⏳ Phase 4	Roadmap
Policy engine	⏳ Phase 5	Roadmap
WASM target	⏳ Phase 6	Roadmap

---

Quick Start

The commands and APIs below reflect the current shipped surface. Higher-level APIs for schemas, encryption, expressions, policies, and WASM remain roadmap items in docs/TODO.md and docs/ARCHITECTURE.md.

CLI

# Install
cargo install dotenvpp-cli

# Check the layered config for a selected environment
dotenvpp check --env production

# Load the layered production stack and run a command with those variables
dotenvpp run --env production -- cargo test

# Or target one explicit file
dotenvpp check --file .env

Rust Crate

fn main() -> Result<(), dotenvpp::Error> {
    dotenvpp::load_with_env("production")?;

    let app_name = dotenvpp::var("APP_NAME")?;
    println!("APP_NAME={app_name}");

    let preview = dotenvpp::from_read(&b"HOST=localhost\nURL=http://${HOST}"[..])?;
    assert_eq!(preview.len(), 2);
    assert_eq!(preview[1].value, "http://localhost");

    Ok(())
}

---

What Makes It Different

vs. dotenv / dotenvy

DotenvPP starts with a from-scratch parser instead of wrapping an existing dotenv crate. That leaves interpolation, layering, schemas, and later roadmap features on top of parser behavior the project owns.

vs. dotenvx

dotenvx is already further ahead on encrypted workflows. DotenvPP is taking a different path: ship a solid Rust parser, interpolation, and layering surface first, then build later phases on that foundation.

vs. HashiCorp Vault / AWS Secrets Manager

Those are infrastructure products. DotenvPP is a developer-facing library and CLI. Even in Phase 0, the goal is local parsing/loading ergonomics rather than replacing secret-management platforms.

vs. SOPS

SOPS is focused on encryption. DotenvPP is broader in roadmap scope, but those later capabilities are still planned work rather than current release features.

---

Architecture

Current workspace layout:

dotenvpp/
├── crates/
│   ├── dotenvpp-parser/    # Phase 0 parser engine
│   └── dotenvpp-cli/       # CLI binary with layered loading support
├── src/lib.rs              # Facade crate API
├── tests/                  # Facade integration tests
├── examples/               # In-crate examples
└── usage-examples/         # Separate demo crate (`publish = false`)

Planned crates such as dotenvpp-schema, dotenvpp-expr, dotenvpp-policy, dotenvpp-crypto, dotenvpp-layers, and dotenvpp-wasm are part of the design vision, not current workspace members. See docs/ARCHITECTURE.md for that longer-term target.

---

Roadmap

Phase	Description	Status
0	Foundation — Standard .env parsing	✅ Complete
1	Interpolation & environment layering	✅ Implemented
2	Schema & type system	📋 Planned
3	Encryption	📋 Planned
4	Expression language	📋 Planned
5	Policy engine	📋 Planned
6	WASM target	📋 Planned
7	DX & ecosystem (VS Code, bindings)	📋 Planned
8	Advanced (remote config, rotation, audit)	📋 Planned

See docs/TODO.md for the detailed roadmap.

---

Research

This project is informed by extensive research into:

• Academic papers: Trend Micro (2022), Basak et al. (2022), OWASP guidelines
• Competitor analysis: dotenvx, SOPS, Infisical, Doppler, Configu, HashiCorp Vault
• Industry standards: 12-Factor App, Policy-as-Code (OPA), Zero Trust Architecture

See docs/RESEARCH.md for the full research synthesis.

---

Tech Stack

• Language: Rust (2021 edition)
• CLI: clap v4
• Parser: custom parser in dotenvpp-parser
• Benchmarking: criterion
• Quality: cargo fmt, clippy, tests, GitHub Actions

Planned later phases introduce additional dependencies such as miette, serde, toml, crabgraph, and wasm-bindgen as those capabilities land.

---

Contributing

DotenvPP has shipped Phase 1 and is moving toward Phase 2. Contributions welcome.

1. Read docs/RESEARCH.md for context
2. Read docs/ARCHITECTURE.md for the technical vision
3. Check docs/TODO.md for the active roadmap, especially interpolation and layering
4. Open an issue or PR

---

The `.env` file hasn't evolved since 2012. It's time.