env-setup

Env Setup

Scan the codebase for environment variable usage, generate or update .env.example, validate .env completeness, and detect leaked secrets.

Anti-hallucination guidelines

Only report variables that are actually found in the code:

1. Grep before reporting: never invent variable names, only list what grep actually returns.
2. Read .env.example before writing: preserve existing entries, only add/update what changed.
3. No actual secrets: .env.example must only contain placeholder values (e.g., your_api_key_here).
4. Verify .gitignore: actually read the file before claiming .env is ignored.
5. Never echo a found secret value: when Phase 6 flags a leaked secret, report the variable name and file:line only. Never print, quote, or write the actual value into chat output, a report file, or anywhere else: the scan's job is to locate leaks, not to create a second one.

Workflow

Phase 1: Scan Codebase

Grep for environment variable usage matching the project's actual language/framework: see references/scan-patterns.md for the ready-to-run pattern per language (Node/TS, Python, Ruby, Rust, Java/Kotlin, Docker Compose, client-exposed prefixes). Only run the pattern(s) for stacks present in the repo.

Also scan:

• .env.example (existing entries to preserve)
• config/ directory for config files referencing env vars
• Framework config files (next.config.js, vite.config.ts, etc.)

Phase 2: Categorize Variables

Group discovered variables by prefix/service: see the service prefix table in references/scan-patterns.md for the standard groupings (Database, Cache, Auth, OAuth, Stripe, AWS, Email, App config, Client vars).

Classify each variable:

• Required vs optional: required if no default/fallback in code.
• Secret vs config: secret if it contains key/secret/password/token in the name.
• Client-exposed: NEXT_PUBLIC_*, VITE_*; flag if it contains secrets.

Phase 3: Compare with .env.example

Read existing .env.example (if it exists):