dotguard

Auto-generate documented .env.example files from your codebase.

Auto-generate documented .env.example files from your codebase.

Ever had a deploy fail because someone added os.getenv("NEW_VAR") but forgot .env.example? dotguard fixes that - automatically.

dotguard scans your codebase and automatically generates a fully documented .env.example - grouped, commented, and ready to commit.

Features

• ⚡ Zero dependencies — pure Python (installs in ~1s)
• 🌍 Language agnostic — Python, JS, TS, shell, YAML, TOML
• 🧠 Smart grouping — auto-groups variables by prefix
• 🔐 Secret detection — flags _KEY, _SECRET, _PASSWORD, _TOKEN
• 🤖 CI-ready — --check fails if .env.example is outdated

Demo

Install

pip install dotguard-scan

Usage

dotguard scan                    # scan current directory → .env.example
dotguard scan ./backend          # scan specific folder
dotguard scan --output prod.env  # custom output filename
dotguard scan --check            # CI mode: exit 1 if undocumented vars found
dotguard diff                    # compare .env vs .env.example, show missing keys
dotguard audit                   # show all vars, which files use them, flag secrets

Quick Demo

🔍 Scanning ./myproject...

  ✔ 23 files scanned
  ✔ 11 environment variables found
  ⚠  3 secrets detected (SECRET_KEY, DB_PASSWORD, AUTH_TOKEN)
  ✔ .env.example written

  Variables by group:
  DATABASE  ████  3 vars
  SMTP      ██    2 vars
  APP       ████  4 vars
  SECRETS   ███   3 vars  ⚠

Generated Output

dotguard produces a clean, grouped .env.example with comments showing where each variable is used:

# ─────────────────────────────────────
# SECRETS  ⚠️  Never commit real values
# ─────────────────────────────────────

# Used in: config.py:4
SECRET_KEY=your-secret-here

# Used in: auth.py:9
AUTH_TOKEN=your-secret-here


# ─────────────────────────────────────
# DATABASE
# ─────────────────────────────────────

# Used in: db.py:12, config.py:3
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Used in: cache.py:8
REDIS_HOST=localhost


# ─────────────────────────────────────
# APP
# ─────────────────────────────────────

# Used in: settings.py:3
DEBUG=true

CI Integration

Add dotguard scan --check to your CI pipeline. It exits with code 1 if any environment variable in your code is missing from .env.example:

# GitHub Actions example
- name: Check env docs
  run: dotguard scan --check

Supported Patterns

License

Licensed under The MIT License.

⭐ Support & Contributing

If you find this project useful, consider:

• ⭐ Starring the repository
• 👤 Following me for more projects
• 🛠️ Contributing to improve the tool

Contributions are always welcome! Feel free to open issues or submit pull requests.