Env Finder

Motivation

Often when doing CI/CD it is really easy to forget to add some env var that should be in prod and then when we deploy things just fail. If we had some way of listing all env vars used and checking that they are all in some list, we can catch this before it hits production.

Overview

Given a directory or list of Python files, env-finder parses the AST and extracts every environment variable name referenced via:

• os.environ["KEY"]
• os.getenv("KEY")
• os.environ.get("KEY")

It can either dump the found var names, or check them against an allowlist file (like a .env) and fail if any are missing.

Install

cargo install --path .

Usage

Dump mode

List all env vars found in Python files:

# Single file
env-finder app.py

# Directory (recursively finds .py files)
env-finder src/

# From stdin
echo 'x = os.environ["DB_URL"]' | env-finder

Output is one var name per line:

DB_URL
API_KEY
NAME

Check mode

Compare found env vars against an allowlist. Exits 1 if any are missing:

env-finder --env-file .env src/

env vars not in .env:
  API_KEY
  SECRET

The allowlist file supports multiple formats:

# Plain names
DB_URL
API_KEY

# .env format (values are ignored, only keys matter)
DB_URL=postgres://localhost/db

# Shell export format
export DB_URL=postgres://localhost/db

# Comments and blank lines are fine
# database
DB_URL

Pre-commit

Add this to your .pre-commit-config.yaml:

repos:
  - repo: git@github.com:Dirac-Software/env-finder.git
    rev: main
    hooks:
      - id: env-finder
        args: ["--env-file", ".env"]

This runs on every staged .py file and fails the commit if any env var isn't in your allowlist.

Testing

# Unit tests (AST parsing, allowlist parsing, missing detection)
# + CLI e2e tests (stdin/files/dirs, check mode, error handling)
cargo test