envcheck-sync 0.1.0

Keep your .env.example in sync with the environment variables your code actually uses.

envcheck

Keep your .env.example in sync with the environment variables your code actually uses.

New teammate clones the repo, copies .env.example, runs the app — and it crashes on a KeyError for some variable nobody documented. envcheck catches that before it happens. It statically scans your Python (it never imports or runs your code) for os.getenv / os.environ access, compares the result to your example env file, and reports:

• Undocumented vars — used in code but missing from .env.example (fails CI)
• Possibly unused vars — in .env.example but never read by any code

Zero runtime dependencies, Python 3.8+, CI-friendly.

Demo

The examples/sample project deliberately drifts from its .env.example so you can try it immediately: envcheck examples/sample.

Installation

pip install envcheck-sync

Or run from a checkout without installing:

PYTHONPATH=src python -m envcheck path/to/project

Usage

# Scan the current directory (auto-detects .env.example, .env.sample, ...)
envcheck .

# Point at a specific example file
envcheck . --env-file config/.env.template

# Machine-readable output for tooling
envcheck . --format json

Example

$ envcheck examples/sample
Scanned 3 env var(s) in code against examples/sample/.env.example.

Undocumented (1 variable used in code, not in the env file):
  - JWT_SECRET  (e.g. examples/sample/app.py:9)

Possibly unused (1 variable in the env file, not read by code):
  - LEGACY_FLAG

envcheck exits non-zero when undocumented variables are found, so it drops straight into CI or a pre-commit hook (use --no-fail to report without failing).

What it detects

Static, literal-key access in these forms:

• os.getenv("X") and getenv("X")
• os.environ.get("X") and environ.get("X")
• os.environ["X"] and environ["X"]
• os.environ.setdefault("X", ...)

Dynamic keys (e.g. os.getenv(some_variable)) are intentionally ignored — envcheck only reports what it can prove statically, so it never produces noisy false positives.

How it works

1. Walk the project and parse each .py file with the standard-library ast module.
2. Collect every literal-key environment-variable access, with its file and line.
3. Parse the example env file for declared variable names.
4. Diff the two sets and report the gaps.

Development

git clone https://github.com/gazzycodes/envcheck
cd envcheck
PYTHONPATH=src python -m unittest discover -s tests -v

Contributions are welcome — please open an issue or PR.

License

MIT — see LICENSE.