dotdrift 0.1.0

Detect drift between .env files — missing, extra, and unset keys

dotdrift

Detect drift between your .env files — locally, in CI, and against your live environment.

---

Install

pip install dotdrift

Or via npm (requires Python 3.11+ on $PATH):

npx dotdrift

---

Quick start

# Compare .env against .env.example (the defaults)
dotdrift check

# Compare two specific files
dotdrift check .env .env.staging

# Fail the build if any extra, undocumented keys exist
dotdrift check --strict

# Pipe JSON output into jq
dotdrift check --json | jq .missing

# Generate a redacted .env.example from your real .env
dotdrift sync .env --output .env.example

# Check the live process environment against a reference
dotdrift live .env.example

# Re-run check every time .env changes (Ctrl+C to stop)
dotdrift watch

---

Python API

from envdiff import compare, parse

# Programmatic diff — accepts file paths, raw strings, or plain dicts
result = compare(".env", ".env.example", strict=True, check_conflicts=True)

if not result.is_clean():
    print("Missing keys:", result.missing)
    print("Unset keys:  ", result.unset)
    print("Conflicts:   ", result.conflicts)
    print(result.summary())

# Parse a .env file directly
parsed = parse(".env")
for key, entry in parsed.entries.items():
    print(f"{key} = {entry.value!r}  (line {entry.line_number})")

---

Commands

check

dotdrift check [SOURCE] [REFERENCE] [OPTIONS]

Compare SOURCE (default: .env) against REFERENCE (default: .env.example) and report missing, extra, unset, or conflicting keys.

Option	Description
--strict	Exit 2 when extra (undocumented) keys exist
--ignore KEY	Exclude KEY from all comparisons (repeatable)
--conflicts	Also detect keys that differ in value
--json	Emit JSON parseable by jq
--quiet / -q	Suppress all output; only set exit code

Exit codes: 0 clean · 1 missing/unset · 2 strict+extra · 3 file not found

---

sync

dotdrift sync [SOURCE] [OPTIONS]

Generate a .env.example from SOURCE with every value redacted (set to ""). A header comment block is prepended automatically.

Option	Description
--output / -o	Output file path (default: .env.example)
--overwrite	Allow overwriting an existing file
--dry-run	Print to stdout; write nothing

---

live

dotdrift live [REFERENCE] [OPTIONS]

Compare os.environ (the live running environment) against REFERENCE. Useful in Docker entrypoints and CI environments to verify all required variables are injected before the application starts.

Option	Description
--ignore KEY	Exclude KEY (repeatable)
--json	JSON output

---

watch

dotdrift watch [SOURCE] [REFERENCE] [OPTIONS]

Poll SOURCE for file changes and re-run check on every save. Uses stat().st_mtime — no external dependencies.

Option	Description
--interval	Poll interval in seconds (default: 2)
--json	JSON output per check

Press Ctrl+C to stop cleanly (exit 0).

---

CI integration

Add this step to your workflow to gate merges on a clean env:

- name: Check .env drift
  run: |
    pip install dotdrift
    dotdrift check .env.ci .env.example --strict

Or pipe JSON results into a downstream step:

- name: Env drift report
  run: dotdrift check --json --quiet > env_report.json

---

Why not just use python-dotenv?

python-dotenv loads .env files into os.environ. dotdrift audits them — it tells you what is missing, what is undocumented, and what has drifted between environments. They solve different problems and work well together.

---

License

MIT — see LICENSE.