Envertor 🔍

Envertor is a CLI tool that generates .env.example files by extracting environment variables from existing .env files or by scanning Python and JavaScript/TypeScript projects. It also helps keep your secrets safe with .gitignore warnings, key parity checks, and CI/CD-ready exit codes.

Install

pip install envertor

Development install:

pip install -e .

---

Usage

Generate .env.example from an existing .env

Strips real values and outputs empty keys by default:

envertor -i .env -o .env.example

Original .env	Generated .env.example
SECRET=mysecret	SECRET=
PORT=8080	PORT=
DEBUG=true	DEBUG=
RATE=3.14	RATE=

Use --placeholder to write type-aware values instead of empty:

envertor -i .env -o .env.example --placeholder

Original .env	With --placeholder
SECRET=mysecret	SECRET=''
PORT=8080	PORT=0
DEBUG=true	DEBUG=false
RATE=3.14	RATE=0.0

---

Scan a project for environment variables

Detects env vars used in source code and generates .env.example from actual usage — no existing .env required:

envertor -p ./my-project -o .env.example

Limit scanning to a specific language:

envertor -p ./my-project --lang python
envertor -p ./my-project --lang js

Supports:

• Python: os.getenv("VAR"), os.environ["VAR"], os.environ.get("VAR")
• JS/TS: process.env.VAR (.js, .ts, .jsx, .tsx)

---

Create .env from .env.example

Bootstrap a local .env from the example file so teammates can fill in their own values:

envertor --create-env                        # reads .env.example by default
envertor --create-env staging.env.example    # reads a custom file

If .env already exists, writes .env.envertor instead to avoid overwriting.

---

Fill empty values from an old .env

Backfill empty keys in your current .env with values from a previous or backup .env:

envertor --complete --from .env.old
envertor --complete .env.staging --from .env.backup

Only strictly empty keys (KEY=) are filled — keys that already have a value (including placeholders like KEY='') are left untouched. Keys present in the source but absent from the target are ignored.

Preview what would be filled without writing anything:

envertor --complete --from .env.old --dry-run

---

Check parity between .env and .env.example

Explicitly verify that both files have the same keys. Designed for CI/CD pipelines — exits 1 on mismatch:

envertor --check
envertor --check --env-file /deploy/.env --example-file /repo/.env.example

Example output on failure:

[envertor] FAIL: Keys mismatch between .env and .env.example
  Missing from .env:          NEW_KEY
  Missing from .env.example:  OLD_KEY

Use in a pipeline:

# GitHub Actions example
- name: Check env parity
  run: envertor --check --env-file .env --example-file .env.example

---

Protect .env in .gitignore

Every envertor run warns if .env is not listed in your repo's .gitignore:

[envertor] WARNING: .env is not listed in .gitignore. Run --protect to fix.

Run --protect to interactively add it. Envertor walks up from your .env location to find the repo root (where .git/ lives), so it works correctly in monorepos:

envertor --protect

[envertor] .env is not listed in .gitignore. Add it now? [y/N]: y
[envertor] Added .env to .gitignore at /repo/.gitignore
[envertor] If .env was previously committed, remove it from git cache:
           git rm --cached .env

If .env is already protected:

[envertor] .env is already protected in .gitignore

---

Quick status check

Running envertor with no arguments prints the .gitignore protection status for the current directory:

envertor

[envertor] .gitignore: /repo/.gitignore
[envertor] .env is protected in .gitignore
Run 'envertor --help' for usage.

If .env is not listed:

[envertor] .gitignore: /repo/.gitignore
[envertor] WARNING: .env is not listed in .gitignore. Run --protect to fix.
Run 'envertor --help' for usage.

If no .gitignore exists yet:

[envertor] .gitignore: not found (repo root: /repo)
[envertor] WARNING: .env is not listed in .gitignore. Run --protect to fix.
Run 'envertor --help' for usage.

---

Show version

envertor -v

---

Automatic safety checks

Every time envertor runs, it performs these checks automatically:

.gitignore warning — warns if .env is not listed in .gitignore (use --protect to fix):

[envertor] WARNING: .env is not listed in .gitignore. Run --protect to fix.

Key parity warning — warns if .env and .env.example have different keys:

[envertor] WARNING: Keys in .env not documented in .env.example: DB_URL
[envertor] WARNING: Keys in .env.example not found in .env: NEW_KEY

Leftover values warning — warns if .env.example contains non-placeholder values:

[envertor] WARNING: .env.example has a real value set for API_KEY

---

Options

Flag	Description
-i, --input FILE	Path to input .env file
-o, --output FILE	Path to output .env.example (default: .env.example)
-p, --project DIR	Project folder to scan for env variable usage
--lang python|js|both	Language filter for project scanning (default: both)
--placeholder	Use type-aware placeholders (0, 0.0, false, '') instead of empty values
--create-env [FILE]	Create .env from FILE (default: .env.example)
--complete [TARGET]	Fill empty keys in TARGET (default: .env) from --from source
--from SOURCE	Source .env file to read values from (used with --complete)
--dry-run	Preview what --complete would fill without writing any changes
--protect	Interactively add .env to .gitignore at repo root
--check	Check key parity and exit 1 on mismatch (CI/CD mode)
--env-file FILE	.env path for --check (default: .env)
--example-file FILE	.env.example path for --check (default: .env.example)
-v, --version	Show version

---

Notes

• Automatically skips node_modules/, venv/, __pycache__/, .next/, .git/, .idea/, .vscode/
• Regex-based scanning catches the most common patterns (os.getenv, os.environ, process.env)
• .env.envertor is a safe backup — rename it to .env or diff it against your existing one
• --protect walks up the directory tree to find .git/, so it works correctly in monorepos

---

License

MIT © Samin Yeasar