Why env-clinic?

You clone a repo. You run npm install. You run npm start. It crashes.

Three environment variables are missing from your .env file but present in .env.example. You spend five minutes debugging a silent failure that should have been obvious.

env-clinic catches this in one second. It's a zero-config CLI that diffs your environment files instantly, so you can stop guessing and start coding.

🚀 Usage

No install required. Just run it in your project root:

npx env-clinic

It automatically finds your .env and looks for an .env.example (or .sample, .template) to compare against.

Requires Node.js 20 or newer.

Empty values like EMPTY= are reported separately. Use --strict if you want those to fail the check.

✨ Output Example

env-clinic checks your .env for completeness and gives you a clear report:

  ✅ DATABASE_URL        — present
  ❌ STRIPE_SECRET_KEY   — MISSING (in example but not in .env)
  ⚠️  OLD_REDIS_URL      — EXTRA (in .env but not in example)
  ⚠️  DEBUG_MODE         — EMPTY (present but has no value)

  💡 Tip: run with --fix to fill these in interactively.

🪄 Auto-Prompt (v1.2.0+)

You don't even need to remember the flags. In an interactive terminal, env-clinic will automatically ask if you want to fix or prune variables on the spot:

❓ Would you like to fill in missing variables now? [y/N]

🛠️ Manual Mode

You can also trigger flags manually:

npx env-clinic --fix

It will prompt you for each missing variable and append it to your .env file safely. If the variable has a default value in your example file, it will be shown as a suggestion — press Enter to accept it.

⚙️ Options

| Flag | Description | Example | |------|-------------|---------| | --fix | Interactive mode to fill in missing variables. Shows example defaults as suggestions. | npx env-clinic --fix | | --prune | Interactive mode to remove EXTRA variables from your .env. | npx env-clinic --prune | | --ci | Plain text output for CI/CD pipelines (no colors/emojis). | npx env-clinic --ci | | --strict | Treats empty variables as errors (exits 1). | npx env-clinic --strict | | --quiet | Only shows errors and warnings. | npx env-clinic --quiet | | --file | Custom path to your .env file. | npx env-clinic --file .env.prod | | --example | Custom path to your reference file. | npx env-clinic --example .env.sample | | --json | Output results as JSON for automation. | npx env-clinic --json | | --version | Show the version number. | npx env-clinic --version | | --help | Show help information. | npx env-clinic --help |

🛡️ CI/CD

Stop broken deployments. Add this to your CI workflow (e.g., GitHub Actions) to ensure all required secrets are present:

- name: Check environment variables
  run: npx env-clinic --ci

env-clinic exits with 0 on match and 1 if anything is missing.

🔒 Security

env-clinic reads only the KEYS from your .env file. It never reads, prints, logs, or transmits your actual secret values. Your secrets stay on your machine.

🤝 Contributing

This is a tiny, focused tool built to solve one specific pain point. If you have a bug fix or a small improvement, feel free to open a PR!

• Found a bug? Open an issue

• Local Dev: npm install and npm test

• PRs: Friendly pull requests are always welcome!

• Contributing Guide

• Changelog

MIT License © 2026 ChloeVPin