Env Example Generator

Developer-friendly CLI that converts existing .env files into safe .env.example templates with human-readable placeholders.

Why?

Sharing .env files is insecure, while keeping .env.example files in sync is tedious. env-example-gen automates template creation, preserving helpful comments and replacing sensitive values with descriptive placeholders so new teammates know exactly what to provide without seeing secrets.

Features

• 🔍 Scans any .env-style file and extracts variables, keeping comments and blank lines intact.
• 🔐 Replaces secrets with contextual placeholders (<YOUR_SECRET_HERE>, <PORT IN NUMBER>, …) using smart key detection.
• 🗃️ Handles single files (default) or every .env* file via --multi.
• 💾 Never logs or emits original values—safe for CI and automation.
• 🪪 Adds a helpful header reminding readers how to use the template.
• 🧪 Provides exit codes suited for pipelines plus a fully tested, modular codebase.

Installation

Use the CLI without installing by running it via npx, or add it to your devDependencies for repeated use.

# Run once
npx env-example-gen

# Or install locally
npm install --save-dev env-example-gen

Usage

npx env-example-gen [options]

Common flows

| Scenario | Command | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Generate .env.example from .env in the current directory | npx env-example-gen | | Read/write custom paths | npx env-example-gen --input ./config/.env.production --output ./templates/.env.production.example | | Process every .env* file (.env, .env.local, .env.production, …) | npx env-example-gen --multi |

CLI options

-i, --input <path>   Path to the source .env file (defaults to ./\.env)
-o, --output <path>  Path for the generated template file
-m, --multi          Generate templates for every .env* file in the current directory
-h, --help           Show usage info

Placeholder detection

env-example-gen inspects variable names and picks meaningful placeholders:

| Pattern | Placeholder | | -------------------------------------------- | -------------------------------------------------- | | PORT | <PORT IN NUMBER> | | URI, URL | <PROTOCOL://USERNAME:PASSWORD@HOST/DATABASENAME> | | HOST | <HOSTNAME> | | PASS, PASSWORD, SECRET, TOKEN, KEY | <YOUR_SECRET_HERE> | | USER | <USERNAME OR EMAIL> | | EMAIL | <EMAIL_ADDRESS> | | EXPIRES_IN, TIMEOUT | <TIME_DURATION> | | (fallback) | <YOUR_VALUE_HERE> |

Examples

Input .env:

PORT=8080
DATABASE_URL=postgres://user:pass@host/db
JWT_SECRET=abcd1234

Generated .env.example:

# Generated by env-example-gen
# Copy this file to .env and replace placeholders with real values.

PORT=<PORT IN NUMBER>
DATABASE_URL=<PROTOCOL://USERNAME:PASSWORD@HOST/DATABASENAME>
JWT_SECRET=<YOUR_SECRET_HERE>

Development

# Install dependencies
npm install

# Type-check & build to dist/
npm run build

# Run the CLI from source
npm run dev -- --help

# Execute the Vitest test suite
npm test

During publishing, npm automatically runs npm run prepare, ensuring the TypeScript sources compile before the package ships.

License

ISC © 2024 Env Example Generator contributors