env-sync-guardian

A powerful CLI tool that treats .env as master and synchronizes all other environment files automatically.

✨ Features

• 🔒 Master-Based Sync: .env is treated as the single source of truth
• 🔍 Auto-Discovery: Automatically finds all .env.* files in your project
• ✅ Check Mode: Compare files without making changes
• 🔧 Fix Mode: Automatically insert missing keys
• 📍 Position-Aware: Keys are inserted at the same position as in master
• 💬 Comment Preservation: Comments from master file are copied to target files
• 🛡️ Safe Values: Never copies values, always inserts KEY=
• 📋 No Sorting: Maintains original file structure
• 🎯 Flexible Configuration: Ignore specific files or add custom paths

📦 Installation

Global

npm install -g env-sync-guardian

Local (per project)

npm install --save-dev env-sync-guardian

Or build from source:

npm install
npm run build

🚀 Usage

Initialize Config File

Create a env-sync-guardian.config.json configuration file in your project:

env-sync-guardian init

This creates a default configuration file that you can customize to your needs.

Check Mode (compare only)

env-sync-guardian check

or with npx:

npx env-sync-guardian check

Fix Mode (insert missing keys)

env-sync-guardian fix

or with npx:

npx env-sync-guardian fix

If using npm scripts:

npm start check
npm start fix

📋 Examples

Master File (.env)

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp

# API Settings
API_KEY=your-api-key
API_URL=https://api.example.com

Target File (.env.production) - Before

DB_HOST=prod-server
DB_NAME=production

API_URL=https://api.production.com

Target File (.env.production) - After Fix

# Database Configuration
DB_HOST=prod-server
# DB_PORT is automatically added here
DB_PORT=
DB_NAME=production

# API Settings
# API_KEY is automatically added here
API_KEY=
API_URL=https://api.production.com

Check Mode Output

$ env-sync-guardian check

[.env.production] Missing keys:
  - DB_PORT
  - API_KEY

[.env.test] Missing keys:
  - API_URL

Fix Mode Output

$ env-sync-guardian fix

[.env.production] Missing keys:
  - DB_PORT
  - API_KEY
→ Fixed .env.production

[.env.test] Missing keys:
  - API_URL
→ Fixed .env.test

⚙️ Configuration

Config File (env-sync-guardian.config.json)

The configuration file is automatically loaded if it exists in your project directory.

Option 1: Using init command (recommended)

env-sync-guardian init

This creates an env-sync-guardian.config.json file with default settings that you can customize.

Option 2: Manual creation

Create an env-sync-guardian.config.json file in your project root:

{
  "masterEnv": ".env",
  "autoDiscover": true,
  "additionalEnvFiles": [],
  "ignore": []
}

Configuration Options

CLI Commands

| Command | Description | Example | |---------|-------------|---------| | env-sync-guardian init | Create config file in current directory | env-sync-guardian init | | env-sync-guardian check | Compare files and report missing keys | env-sync-guardian check | | env-sync-guardian fix | Insert missing keys into target files | env-sync-guardian fix |

masterEnv

Defines the master environment file path.

"masterEnv": ".env"

or with a full path:

"masterEnv": "./config/.env"

| Type | Description | |------|-------------| | string | Path to the master .env file (relative or absolute) |

autoDiscover

Automatically discover all .env.* files in the project directory.

"autoDiscover": true

| Type | Default | Description | |------|---------|-------------| | boolean | true | Enable/disable automatic file discovery |

additionalEnvFiles

Manually specify additional environment files to sync.

"additionalEnvFiles": [
  ".env.staging",
  "config/.env.custom"
]

| Type | Description | |------|-------------| | string[] | Array of file paths relative to project root |

ignore

Exclude specific files from synchronization.

"ignore": [
  ".env.local",
  ".env.backup"
]

| Type | Description | |------|-------------| | string[] | Array of file names to ignore |

🔄 Workflow

1. Initialize: Run env-sync-guardian init to create a configuration file
2. Customize: Edit env-sync-guardian.config.json according to your needs
3. Check: Run env-sync-guardian check to see which keys are missing
4. Fix: Run env-sync-guardian fix to automatically insert missing keys
5. Fill Values: Manually add the appropriate values for the inserted keys
6. Verify: Run check again to confirm all files are in sync

💡 Use Cases

• Multi-Environment Projects: Keep .env.development, .env.staging, and .env.production in sync
• Team Collaboration: Ensure all team members have the same environment variables
• CI/CD Pipelines: Validate environment files before deployment
• Onboarding: Help new developers identify missing configuration keys

📄 Requirements

• Node.js >= 16.0.0
• npm >= 7.0.0

📝 License

MIT License