envsniff 0.1.0

Scan codebases for environment variables, detect undocumented vars, and generate .env.example files

envsniff

Scan codebases for environment variables, detect undocumented vars, and generate .env.example files — with or without AI-written descriptions.

No more "what env vars do I need to run this?" — envsniff finds them all and documents them for you.

---

Table of Contents

• Why envsniff
• Architecture
• How it works
• Install
• Usage
  • scan
  • generate
  • check
• Supported languages
• Technologies
• AI descriptions
• Pre-commit hook
• GitHub Action
• CI integration
• Configuration
• Output formats

---

Why envsniff

Most teams document environment variables manually — and it's always out of date. envsniff fixes this by reading the code directly.

Tool	Gap
dotenv-linter	Lints .env files only — does not scan source code
sync-dotenv	Syncs .env → .env.example, requires an existing .env
detect-secrets	Security-focused; finds secrets, not documentation
env-checker	Runtime validation, not a scanner

envsniff is the only tool that scans your source code, finds every os.getenv() / process.env.X / os.Getenv() call, and generates a documented .env.example from scratch.

---

Architecture

src/envsniff/
├── models.py           # Immutable dataclasses (SourceLocation, EnvVarFinding, ScanResult)
├── errors.py           # Exception hierarchy
├── config.py           # .envsniff.toml / pyproject.toml loader
├── scanner/
│   ├── engine.py       # Orchestrates walk → dispatch → deduplicate
│   ├── file_walker.py  # .gitignore-aware recursive walk (pathspec)
│   ├── registry.py     # Maps file extensions to plugins
│   ├── type_inferrer.py
│   └── plugins/        # One file per language
├── env_example/
│   ├── parser.py       # Reads existing .env.example preserving structure
│   ├── merger.py       # new / stale / existing classification
│   └── writer.py       # Atomic write (temp → rename)
├── describer/
│   ├── types.py        # Name → InferredType rules
│   ├── fallback.py     # Heuristic descriptions (no API needed)
│   ├── cache.py        # SHA-256 keyed JSON cache
│   └── ai.py           # Multi-provider AI descriptions (Anthropic, OpenAI, Gemini, Ollama)
├── hooks/
│   ├── precommit.py    # Staged-files-only scan
│   └── ci.py           # Full scan with JSON output
└── cli/
    ├── main.py         # Click commands: scan / generate / check
    └── formatters.py   # table / json / markdown renderers

---

How it works

flowchart TD
    A[Your codebase] --> B[File Walker]
    B -->|respects .gitignore| C[Scanner Registry]
    C --> D1[Python plugin\nos.getenv / os.environ]
    C --> D2[JavaScript plugin\nprocess.env.X]
    C --> D3[Go plugin\nos.Getenv]
    C --> D4[Shell plugin\n$VAR / $VARNAME]
    C --> D5[Docker plugin\nENV / ARG]
    D1 & D2 & D3 & D4 & D5 --> E[Scanner Engine\ndeduplication + type inference]
    E --> F{Command}
    F -->|scan| G[Formatted output\ntable / json / markdown]
    F -->|generate| H[.env.example Parser]
    H --> I[Merger\nnew / stale / existing]
    I --> J[AI Describer\noptional]
    J --> K[Atomic Writer\n.env.example]
    F -->|check| L{All vars documented?}
    L -->|yes| M[exit 0 ✓]
    L -->|no| N[exit 1 ✗\nlist undocumented vars]

The merge strategy

When running envsniff generate, existing human-written comments are always preserved:

Var state	Action
In code + in .env.example	Keep as-is (preserve human description)
In code, missing from .env.example	Add with # Added by envsniff
In .env.example, not in code	Comment out with # UNUSED (not found in codebase):

---

Install

macOS / Linux

pip install envsniff

Windows

pip install envsniff

Via npm / npx (any OS)

npx envsniff scan .

Local development (after cloning)

# macOS / Linux
git clone https://github.com/harish124/envsniff.git
cd envsniff
pip install -e .

# Windows
git clone https://github.com/harish124/envsniff.git
cd envsniff
pip install -e .

The -e flag installs in editable mode — changes to the source take effect immediately without reinstalling.

---

Usage

scan

Find all environment variables in a codebase:

envsniff scan .
envsniff scan ./src --format json
envsniff scan . --format md
envsniff scan . --exclude "tests/*" --exclude "*.sh"

Example output:

┌──────────────────┬─────────┬──────────┬─────────┬─────────────────┐
│ Name             │ Type    │ Required │ Default │ Locations       │
├──────────────────┼─────────┼──────────┼─────────┼─────────────────┤
│ DATABASE_URL     │ URL     │ yes      │ —       │ app.py:12       │
│ API_KEY          │ SECRET  │ yes      │ —       │ client.py:8     │
│ DEBUG            │ BOOLEAN │ no       │ false   │ settings.py:3   │
│ PORT             │ INTEGER │ no       │ 8080    │ server.py:1     │
└──────────────────┴─────────┴──────────┴─────────┴─────────────────┘
Scanned 42 files · Found 4 variables

generate

Create or update .env.example:

envsniff generate .
envsniff generate . --output .env.example
envsniff generate . --ai          # prompts for provider + model interactively
envsniff generate . --no-ai       # skip AI, use heuristic descriptions
envsniff generate . --ai --ai-provider openai --ai-model gpt-4o   # non-interactive

Example .env.example output:

# Added by envsniff
#
# Description: PostgreSQL/MySQL connection string
# Example:     postgres://user:pass@localhost/dbname
#
DATABASE_URL=

# Added by envsniff
#
# Description: Api API key
#
API_KEY=

# Added by envsniff
#
# Description: Enable debug mode (true/false)
# Example:     false
#
DEBUG=false

# Added by envsniff
#
# Description: Port number the server listens on
# Example:     8080
#
PORT=8080

Heuristic descriptions are always generated — no --ai flag needed. The # Example: line is omitted when no example value is known.

check

Use in CI or pre-commit to enforce documentation:

envsniff check .                  # exit 1 if undocumented vars exist
envsniff check . --fail-on-stale  # also exit 1 if stale vars in .env.example
envsniff check . --strict         # fail on any issue

---

Supported languages

Language	Patterns detected
Python	os.getenv("X"), os.environ.get("X"), os.environ["X"]
JavaScript / TypeScript	process.env.X, process.env["X"]
Go	os.Getenv("X"), os.LookupEnv("X")
Shell	$VAR, ${VAR} — skips local variables (VAR=value without export), shell specials ($$, $?, $1–$9)
Dockerfile	ENV VAR=value, ARG VAR=default

---

Technologies

Library	Purpose
Click	CLI framework
tree-sitter	AST-based source code parsing per language
questionary	Interactive terminal prompts with arrow-key navigation
pathspec	.gitignore-aware file walking
anthropic	Anthropic Claude AI descriptions
openai	OpenAI / Grok / Perplexity AI descriptions
google-generativeai	Google Gemini AI descriptions
ollama	Local Ollama AI descriptions

---

AI descriptions

All AI providers are bundled with envsniff — no extra install step. Pass --ai and you will be prompted to choose a provider and model interactively:

$ envsniff generate . --ai

? Which AI provider?
  1. Anthropic (Claude)
❯ 2. OpenAI (GPT)
  3. Google Gemini
  4. Ollama (local)

  Tip: check the official openai documentation for available models.
? Which model? (e.g. gpt-4o-mini): gpt-4o

Use arrow keys to select a provider, Enter to confirm. Model name is required — leaving it blank will error.

Or skip the prompts by passing flags directly (useful for CI):

envsniff generate . --ai --ai-provider openai --ai-model gpt-4o

Set the API key for your chosen provider before running:

Provider	API key env var	Notes
Anthropic	ANTHROPIC_API_KEY	Default provider
OpenAI	OPENAI_API_KEY	Also works for Grok, Perplexity via OPENAI_BASE_URL
Gemini	GEMINI_API_KEY
Ollama	—	Local, no key needed

• Batches up to 20 vars per API call
• Caches results in ~/.cache/envsniff/descriptions.json — API is never called twice for the same var
• Falls back to heuristic descriptions if the provider is unavailable

Privacy

envsniff scrubs code snippets before sending anything to the AI provider. Default values (the second argument in calls like os.environ.get("KEY", "value")) are stripped using regex so only the variable name and call structure are transmitted:

# What's in your code:
db = os.environ.get("DATABASE_URL", "postgres://user:secret@prod/db")

# What the AI receives:
os.environ.get("DATABASE_URL")

What is never sent: .env file contents, actual secret values, or any string literals used as defaults.

Disclaimer — known limitation: The scrubbing works on single-line calls. If a default value spans multiple lines, the regex cannot reliably detect it and that line may be sent as-is:

# Multi-line call — default value on its own line may not be scrubbed:
url = os.environ.get(
    "DATABASE_URL",
    "postgres://user:secret@prod/db"   # ← this line could be sent
)

This is an inherent limitation of line-by-line text scrubbing. The fix would require full AST-level analysis, which is not currently implemented. To be safe, avoid hardcoding real secrets as default values in your source code — use placeholder strings like "postgres://localhost/mydb" instead.

---

Pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/harish124/envsniff
    rev: v0.1.0
    hooks:
      - id: envsniff-check

This blocks commits that introduce undocumented environment variables.

---

GitHub Action

Add envsniff to any repository in seconds. On every pull request it scans your code, updates .env.example, and commits the result automatically — no manual step needed.

# .github/workflows/envsniff.yml
name: Sync .env.example

on:
  pull_request:
    branches: [main, master]

jobs:
  envsniff:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
          fetch-depth: 0

      - uses: harish124/envsniff@v1
        with:
          path: "."
          commit: "true" # auto-commit updated .env.example
          fail-on-drift: "false" # set "true" to block merges on undocumented vars
          commit-message: "chore: sync .env.example [skip ci]"

Action inputs

Input	Default	Description
path	.	Directory to scan
commit	true	Commit updated .env.example back to the PR branch
fail-on-drift	false	Block the merge when new undocumented variables are found
commit-message	chore: sync .env.example	Commit message for the auto-commit
python-version	3.12	Python version used to install envsniff

Action outputs

Output	Description
new-vars	Comma-separated list of newly found variables not yet in .env.example
stale-vars	Comma-separated list of variables in .env.example no longer in code
scanned-files	Number of source files scanned
drift-detected	true when new undocumented variables were found

Requires: Repository Settings → Actions → General → Workflow permissions → Read and write permissions

A ready-to-copy workflow file is available at .github/examples/envsniff.yml.

---

CI integration

# .github/workflows/ci.yml
- name: Check env vars are documented
  run: envsniff check . --strict

For machine-readable output in CI logs:

envsniff check . --format json

status: fail
new_vars[1]: NEW_SECRET
stale_vars[0]:
scanned_files: 42

---

Configuration

Create .envsniff.toml in your project root (or add [tool.envsniff] to pyproject.toml):

[tool.envsniff]
exclude = ["tests/*", "scripts/*", "*.sh"]
output = ".env.example"
ai = false
ai_provider = "anthropic"   # anthropic | openai | gemini | ollama
ai_model = ""               # leave empty to be prompted, or set a specific model

---

Output formats

scan and check support --format table (default), --format json, and --format md.

JSON — for scripting and CI:

findings[1]:
  - name: DATABASE_URL
    inferred_type: URL
    is_required: true
    default_value: null
    language: python
    locations[1]{file,line}:
      app.py,12
scanned_files: 42
errors[0]:

Markdown — for documentation:

| Name         | Type    | Required | Default |
| ------------ | ------- | -------- | ------- |
| DATABASE_URL | URL     | yes      | —       |
| DEBUG        | BOOLEAN | no       | false   |