Diagnose environment-variable drift before configuration breaks production.
EnvDoctor is a local-first Python CLI (with a modern GUI) that compares environment files with variables referenced by source code. It detects missing, duplicated, undocumented, unused, placeholder, and potentially sensitive values — without ever printing secret contents.
- Parses
.envand.env.examplefiles with strict syntax checks (ENV001–ENV011) - Finds env-var references across Python, JavaScript, TypeScript, shell, YAML, JSON, Go, Rust, Java, Ruby, and PHP
- Reports missing variables and
.env.exampledrift - Flags duplicate keys, placeholders, unused variables, and likely secrets
- Typed schema validation (ENV501–ENV503): int, port, bool, url, enum, required, ranges, allowed choices
- Multi-environment profiles: compare
.env.development,.env.staging,.env.production - Auto-fix (
fix): safely repair formatting issues with--dry-run - Watch mode (
watch): re-scan automatically on file changes - Redacts all values from console and generated reports
- Exports text, JSON, HTML, and SARIF 2.1.0
- Generates a starter
pydantic-settingsmodel - Returns CI-friendly exit codes
- Modern GUI: dark-themed desktop app with scan, diff, fix, export, and watch mode
- Includes tests and GitHub Actions workflows
Double-click start.bat to launch the modern GUI.
Or use the CLI:
start-cli.bat check .
start-cli.bat diff .env .env.example
start-cli.bat fix .env --dry-run
start-cli.bat generate --env .env.example -o settings.pyMake the script executable, then run:
chmod +x start.sh
./start.shOr use the CLI:
chmod +x start-cli.sh
./start-cli.sh check .
./start-cli.sh diff .env .env.example
./start-cli.sh fix .env --dry-runBoth scripts automatically install Python dependencies and launch EnvDoctor.
python -m venv .venv
# Windows: .venv\Scripts\python -m pip install -e .
# macOS/Linux:
.venv/bin/python -m pip install -e .For the GUI, also install PyQt6:
pip install PyQt6envdoctor check .
envdoctor check . --env .env.local --example .env.example
envdoctor check . --format json -o envdoctor.json
envdoctor check . --format html -o envdoctor.html
envdoctor check . --format sarif -o envdoctor.sarif
envdoctor diff .env .env.example
envdoctor fix .env --dry-run
envdoctor fix .env
envdoctor generate --env .env.example -o settings.py
envdoctor validate --env .env --example .env.example
envdoctor watch . --interval 2
envdoctor-guiRun the included intentionally unhealthy example:
envdoctor check examples --env .env --example .env.example --fail-on never
envdoctor check examples --env .env --example .env.example --format html -o report.html --fail-on never| Rule | Meaning | Default severity |
|---|---|---|
| ENV001 | Invalid dotenv syntax | Error |
| ENV002 | Duplicate key | Error |
| ENV003 | Key without value | Error |
| ENV004 | Spaces around = delimiter |
Error |
| ENV005 | Lowercase key | Warning |
| ENV006 | Trailing whitespace | Warning |
| ENV007 | Missing trailing newline | Info |
| ENV008 | Incorrect delimiter (: instead of =) |
Error |
| ENV009 | Trailing comment inside value | Warning |
| ENV010 | Mismatched quotes | Warning |
| ENV011 | Extra blank line | Warning |
| ENV101 | Referenced key missing from selected env file | Error |
| ENV102 | Referenced key missing from example contract | Warning |
| ENV201 | Defined key has no detected source reference | Warning |
| ENV202 | Example key not present in selected env file | Info |
| ENV301 | Empty or placeholder-like value | Warning |
| ENV401 | Potential secret value detected | Error |
| ENV501 | Value fails schema type check | Error |
| ENV502 | Value out of range / not in allowed choices | Error |
| ENV503 | Profile variable missing from base env | Error |
[env]
file = ".env"
example = ".env.example"
[rules]
ENV201 = "ignore" # Ignore unused-variable warnings
ENV005 = "warning" # Lowercase keys are warnings
[ignore]
paths = ["docs", "legacy"]
keys = ["UNUSED_FLAG", "CI"]
[ci]
fail_on = "warning"
[[schema]]
key = "PORT"
type = "port"
required = true
[[schema]]
key = "NODE_ENV"
type = "enum"
choices = ["development", "staging", "production"]
[[schema]]
key = "DATABASE_URL"
type = "url"
required = true
[[schema]]
key = "DEBUG"
type = "bool"
dev_default = "true"
[[schema]]
key = "API_KEY"
type = "str"
sensitive = true
required_in_prod = true
profiles = ["development", "staging", "production"]EnvDoctor never includes environment values in findings or reports. Secret detection is intentionally conservative and uses key names, value length, and entropy. A finding is a prompt to investigate, not proof that a credential is valid.
- Static pattern matching cannot see every framework-specific configuration mechanism.
- Variables consumed only by cloud platforms, Docker, deployment manifests, or external systems can appear unused.
- Multiline dotenv values and shell interpolation are parsed conservatively.
- Secret detection can produce false positives and does not replace a dedicated secret scanner.
python -m pip install -e ".[dev]"
ruff check .
pytest -q
python -m build- Framework adapters for Django, FastAPI, Next.js, Vite, Docker Compose, and Kubernetes
- Interactive repair with suggested edits
- Monorepo workspaces and environment profiles
- Git history checking through a dedicated secret-scanner adapter
- Pre-commit hook integration
- Desktop UI enhancements (already available via
envdoctor-gui)
MIT
| Document | Purpose |
|---|---|
| USER_GUIDE.md | Full user guide with examples and troubleshooting |
| CHANGELOG.md | Version history and changes per release |
| RELEASE_LOG.md | Release dates and release notes |
| AUDIT.md | Feature audit and roadmap analysis |