envsleuth 0.1.1

Detective for env vars in Python code. Parses your source with AST, finds every os.getenv/os.environ usage, and tells you what's missing from your .env file.

envsleuth

🕵️ The detective for env vars in Python code. Parses your source with AST, finds every os.getenv() / os.environ[] / os.environ.get(), and tells you what's missing from your .env file.

No more shipping to prod and realising you forgot STRIPE_API_KEY.

Install

pip install envsleuth

Usage

# scan current directory, check against ./.env
envsleuth scan

# specific directory, specific env file
envsleuth scan --path ./src --env .env.production

# CI mode — exits 1 if anything is missing
envsleuth scan --strict

# generate a .env.example from your code
envsleuth generate

# machine-readable output
envsleuth scan --json

Example output

Found 6 variables in code
checking against .env

⚠️  AWS_SECRET — not in .env but has default in code (probably ok)
✅ DATABASE_URL
✅ DEBUG
❌ REDIS_URL — missing from .env
     at src/app.py:7
✅ SECRET_KEY
❌ STRIPE_API_KEY — missing from .env
     at src/app.py:6

⚠️  1 dynamic usage (variable name computed at runtime, can't check statically)
     src/app.py:12  →  getenv(name)

ℹ  1 variable in .env not referenced in code: UNUSED_VAR

3 ok  1 with default  2 missing

What it detects

Works with all three common patterns:

import os

a = os.getenv("A")              # required — must be in .env
b = os.getenv("B", "fallback")  # has default — warned but not required
c = os.environ["C"]             # required (would raise KeyError without)
d = os.environ.get("D")         # required

Also handles aliased imports:

from os import getenv, environ
import os as sys_os

a = getenv("A")
b = environ["B"]
c = sys_os.getenv("C")

Variables with names computed at runtime (e.g. os.getenv(f"PREFIX_{x}")) can't be checked statically — they're reported in a separate warning section so you know they exist.

envsleuth generate

Scans your code and writes a .env.example with every variable found, a comment pointing at where it's used, and the default value from code if there is one:

$ envsleuth generate
Wrote 6 variables to .env.example

$ cat .env.example
# Generated by envsleuth — edit this file before committing.
# Each variable below is used somewhere in your code.

# used at src/app.py:8
AWS_SECRET=default-value

# used at src/app.py:3
DATABASE_URL=

# used at src/app.py:5
DEBUG=false
...

Use --force to overwrite an existing file, --output path/to/file to write elsewhere.

.envignore

Exclude variables from the "missing" check with glob patterns — one per line:

# .envignore
TEST_*
LEGACY_*
DEBUG_TOOL

Great for vars that come from CI, Docker, or your shell rc files rather than the local .env.

CI usage

GitHub Actions:

- name: Check env vars
  run: |
    pip install envsleuth
    envsleuth scan --env .env.example --strict

pre-commit:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: envsleuth
      name: envsleuth
      entry: envsleuth scan --strict
      language: system
      pass_filenames: false

CLI reference

envsleuth scan

Flag	Description
--path, -p	Directory or file to scan. Default: .
--env	Path to .env file. Default: ./.env
--envignore	Path to .envignore. Default: ./.envignore if present
--strict	Exit with code 1 if vars are missing
--json	JSON output for CI pipelines
--no-color	Disable ANSI colors (also honours NO_COLOR env var)
--exclude DIR	Extra directory name to skip. Can be repeated
--ext .EXT	Extra file extension to scan (e.g. .pyi). Can be repeated
--verbose, -v	Show usage locations for every variable

envsleuth generate

Flag	Description
--path, -p	Directory or file to scan. Default: .
--output, -o	Where to write. Default: ./.env.example
--force, -f	Overwrite existing output file
--no-color	Disable ANSI colors in the success message
--exclude, --ext	Same as in scan

How it compares

	envsleuth	dotenv-linter	python-decouple
Scans your code for env var usages	✅	❌	❌
Lints the .env file itself	❌	✅	❌
Runtime config reader with casting	❌	❌	✅
Generates .env.example from code	✅	❌	❌
Language	Python	Rust	Python

envsleuth is the only tool here that understands your source code. The others either look at your .env file in isolation, or read env vars at runtime.

Dependencies

• click — CLI
• python-dotenv — .env parsing
• flashbar — progress bar (a tiny zero-dep lib I wrote; envsleuth uses it when scanning 20+ files)

The scanner itself uses only the Python standard library (ast).

License

MIT