Skip to content
PeaBox-LabPublic

About

A developer-friendly CLI for finding broken, missing, unused, and unsafe environment variables.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

EnvDoctor

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.

What v0.2 does

  • Parses .env and .env.example files 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.example drift
  • 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-settings model
  • 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

Quick Start (one-click launch)

Windows

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.py

Linux / macOS

Make the script executable, then run:

chmod +x start.sh
./start.sh

Or 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-run

Both scripts automatically install Python dependencies and launch EnvDoctor.

Install from source

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 PyQt6

Use

envdoctor 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-gui

Run 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

Rules

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

Configuration (envdoctor.toml)

[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"]

Safety choices

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.

Known limits

  • 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.

Developer setup

python -m pip install -e ".[dev]"
ruff check .
pytest -q
python -m build

Roadmap

  • 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)

License

MIT

Documentation

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

About

A developer-friendly CLI for finding broken, missing, unused, and unsafe environment variables.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages