env-sanity

Environment file validator and sync utility for teams

A simple, powerful tool to keep your environment files in sync across different environments. Perfect for teams working with multiple .env files (.env.prod, .env.qa, .env.staging, etc.).

✨ Features

• 🔍 Compare environment files against templates
• 🔄 Sync missing keys across environments
• 📁 Smart file resolution (finds .env.prod, .prod, etc.)
• 💬 Interactive confirmation before making changes
• 🏗️ CI/CD friendly with proper exit codes
• 📦 Dual usage: CLI tool + importable library

🚀 Quick Start

Installation

# Global installation (recommended for CLI usage)
npm install -g env-sanity

# Or use with npx (no installation needed)
npx env-sanity --help

Basic Usage

# Compare your .env against template
env-sanity compare .env .env.example

# Sync missing keys from master to targets
env-sanity sync --master .env.prod .env.qa .env.staging

# Compare multiple files against master
env-sanity compare-master --master .env.prod .env.qa .env.staging

📖 Commands

compare <actual> <template>

Compare an actual environment file against a template/reference file.

env-sanity compare .env .env.example
env-sanity compare .env.qa .env.prod

Output:

🔍 Comparing .env against template .env.example
⚠️  Missing in .env (required by template): DATABASE_NAME, STRIPE_SECRET_KEY
➕  Extra in .env (not in template): LOCAL_DEV_MODE

sync --master <file> <targets...>

Add missing keys from master file to target files with empty placeholders.

env-sanity sync --master .env.example .env
env-sanity sync --master .env.prod .env.qa .env.staging

Features:

• ✅ Preserves comments and file structure
• ✅ Interactive confirmation before changes
• ✅ Safe empty placeholders (no value copying)

compare-master --master <file> <targets...>

Compare multiple files against a master file (great for CI/CD).

env-sanity compare-master --master .env.prod .env.qa .env.staging

📁 File Resolution

env-sanity automatically finds your environment files using smart patterns:

env-sanity compare .prod .qa
# Tries: .prod, .env.prod, .env.prod
# Tries: .qa, .env.qa, .env.qa

Search locations:

1. Current directory
2. environment/ directory (if exists)

🔧 Programmatic Usage

Use env-sanity as a library in your Node.js projects:

import { compareEnvs, parseEnvFile } from "env-sanity";

const env1 = parseEnvFile(".env");
const env2 = parseEnvFile(".env.example");

const result = compareEnvs(env1, env2);
console.log("Missing keys:", result.missing);
console.log("Extra keys:", result.extra);

🏗️ CI/CD Integration

env-sanity returns proper exit codes for CI/CD pipelines:

# GitHub Actions example
- name: Validate environment files
  run: env-sanity compare .env.example .env.prod

• Exit code 0: Files are in sync ✅
• Exit code 1: Differences found ❌

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

👨💻 Author

Created and maintained by Jeffrey Davies

📄 License

MIT © Jeffrey Davies

🙏 Acknowledgments

Built with:

• TypeScript - Type safety and modern JavaScript features
• Node.js - JavaScript runtime environment
• commander.js - Powerful CLI framework with subcommands
• dotenv - Environment file parsing and validation