A CLI wrapper that detects and repairs missing environment variables before your app starts.
Installation • Quick Start • Features • FAQ • Command Reference
Stop crashing your development server because your .env is out of sync with .env.example. envrepair compares your active .env against the template, repairs missing variables interactively, then launches your command while preserving comments, spacing, blank lines, and ordering.
Install envrepair as a development dependency so it is available to all team members after npm install:
# npm
npm install -D envrepair
# pnpm
pnpm add -D envrepair
# yarn
yarn add -D envrepairThen, prepend your startup scripts in package.json:
"scripts": {
"dev": "envrepair next dev"
}Install globally or run on-demand without a local installation:
# Install globally
npm install -g envrepair
# Or run instantly on demand
npx envrepair [command]Simply prepend your normal development command with envrepair:
envrepair next devWhenever this command is run, envrepair will:
- Scan: Compares your local
.env(or.env.local) against.env.example. - Prompt & Validate: Interactively prompts you in the terminal for any missing keys, validating formats (like numbers, URLs, and emails) and masking sensitive credentials.
- Save: Appends the new variables to your
.envfile safely, preserving all of your existing comments, spacing, blank lines, and ordering. - Spawn: Instantly starts your target command (
next dev) as a transparent child process, passing signals (likeCtrl+C) and exit codes down to the shell.
Example session:
$ envrepair next dev
Missing 2 required environment variable(s)
DATABASE_URL
Enter value: postgres://localhost/mydb
API_SECRET_TOKEN
Enter value (hidden): **************
Appended 2 repaired variable(s) to .env.
> next dev
walkthrough.mp4
- Preserves your
.envexactly as you organized it. Comments, spacing, blank lines, and ordering stay intact. - Rejects invalid formats before they reach your application. Validates URLs, emails, numbers, and booleans in real-time using
# @typeannotations in your template. - Masks credentials automatically. Any key matching common sensitive patterns (PASSWORD, SECRET, TOKEN, KEY, etc.) is prompted with hidden input.
- Behaves like your original command.
Ctrl+C, exit codes, and terminal output work exactly as expected. - Automatically detects CI environments and exits with status 1 instead of hanging on interactive prompts.
.env.example
│
▼
Compare with .env
│
Missing keys?
┌───┴───┐
│ │
Prompt Launch
│
Update .env
│
Launch
envrepair wraps any development command. It is not tied to a specific framework or runtime.
next dev node server.js vite
npm run dev bun run dev astro dev
nest start remix dev python manage.py runserver
Add # @type <type> annotations to .env.example to validate inputs during prompts:
# @type url
API_BASE_URL=API_BASE_URL:
Enter value: localhost
❌ Invalid url
Enter value: https://api.example.com
✓
Supported validation types: string, number, boolean, url, email.
Does envrepair overwrite existing values?
No. Only variables that are missing from your .env are appended. Existing values are never modified.
Is this intended for production?
No. envrepair is designed for local development. In CI environments it skips prompts entirely and exits with status 1 if variables are missing, so it integrates cleanly into pipelines without hanging.
| Feature | envrepair |
dotenv-safe |
sync-dotenv |
envalid |
t3-env |
|---|---|---|---|---|---|
| Works as a CLI wrapper | ✅ | ❌ | ✅ | ❌ | ❌ |
| Requires explicit validation definition | ❌ | ❌ | ❌ | ✅ | ✅ |
| Auto-repairs missing variables | ✅ | ❌ | ❌ | ❌ | ❌ |
| Interactive terminal prompts | ✅ | ❌ | ❌ | ❌ | ❌ |
| Preserves comments, spacing, blank lines, and ordering | ✅ | ❌ | ❌ | ❌ | ❌ |
| Input masking for secrets | ✅ | ❌ | ❌ | ❌ | ❌ |
| Interactive typed input prompts | ✅ | ❌ | ❌ | ❌ | ❌ |
| Schema-based validation (Zod, etc.) | ❌ | ❌ | ❌ | ❌ | ✅ |
Note
envrepair focuses on interactive environment setup and automatic repair before your application starts. Tools like t3-env and envalid focus on validating environment variables inside your application at runtime. These tools solve different problems and can be used together.
dotenv-safe intentionally fails fast, crashing your app if variables are missing and leaving you to find and fix them manually. envrepair guides you through repairing them interactively before your app ever starts.
These are runtime schema validators that live inside your application code. They are excellent at validating the types and shapes of variables your app depends on. envrepair works at the terminal layer before your app boots. They solve different problems and can be used together.
sync-dotenv automatically copies missing keys from .env.example into .env with empty values. It does not prompt you to fill them in, and it destroys your existing comments, spacing, and ordering in the process.
envrepair [target-command]Checks environment validity, runs interactive repair if needed, then runs the target command.
envrepair doctorOutputs a status report of synced, missing, and unused variables. Exits with status 1 if missing variables exist.
envrepair repairRuns the interactive terminal prompt flow to repair missing variables without starting a target process.
envrepair diff [--json]Shows differences between the active and template environment files. Outputs plain text or structured JSON.
envrepair checkRuns validation without interactive prompts, outputs differences in JSON, and exits with status 1 if variables are missing. Designed for CI/CD scripting.
-e, --env <path>: Path to the active env file (defaults to.env).-x, --example <path>: Path to the template example file (defaults to.env.example).-h, --help: Displays help information.
In headless environments, envrepair skips prompts and exits with status 1 if variables are missing:
# Validates environment state and exits with 0 or 1.
envrepair check