usopp 🎯

"I'm going to be the greatest sniper in the world — and I never miss an env variable."

usopp scans your entire project for every environment variable reference and generates a .env.usopp template so your team never ships broken configs again.

Install

# globally
npm install -g usopp

# or run without installing
npx usopp

Usage

# Scan the current directory and write .env.usopp
usopp

# Scan a specific project
usopp --dir ./my-project

# Custom output path
usopp --dir ./my-project --out ./infra/.env.template

# Preview without writing any file
usopp --dry

# Strip source-file comments from output
usopp --no-comments

# Suppress terminal output
usopp --quiet

What it detects

| Language / Tool | Pattern | |---|---| | JavaScript / TypeScript | process.env.FOO, process.env['FOO'] | | Vite | import.meta.env.VITE_FOO | | Python | os.environ['FOO'], os.getenv('FOO') | | Ruby | ENV['FOO'], ENV.fetch('FOO') | | Shell / Dockerfile | $FOO, ${FOO} | | Docker Compose / YAML | KEY= assignments, ${KEY} references | | Terraform | ${VAR} interpolations |

Output

Running usopp produces a .env.usopp file like this:

# ─────────────────────────────────────────────
# .env.usopp — generated by usopp
# Scanned root: /your/project
# Generated at: 2026-04-13T00:00:00.000Z
# ─────────────────────────────────────────────

# ── AWS ──
# found in: api/server.js:14  |  docker-compose.yml:9
AWS_REGION=
AWS_S3_BUCKET=

# ── DB ──
# found in: api/server.js:2,3,4,5,6  |  docker-compose.yml:6,7
DB_HOST=
DB_NAME=
DB_PASSWORD=
DB_PORT=
DB_USER=

Variables are grouped by prefix (DB_, AWS_, VITE_, etc.) and each entry notes exactly which files and line numbers reference it.

Recommended workflow

1. Run usopp at project setup or in CI.
2. Copy .env.usopp → .env and fill in real values.
3. Add .env to .gitignore, commit .env.usopp as a documented template.
4. Re-run usopp whenever you add new variables to keep the template fresh.

Programmatic API

const { scanProject, generateEnvFile } = require("usopp");

const { variables, scannedCount } = await scanProject("/path/to/project");
const content = generateEnvFile(variables, "/path/to/project");
console.log(content);

License

MIT