ENV File Manager

A CLI tool to sync and validate environment variables across multiple projects. Keep your .env files consistent, validate required variables, and generate new environment files from templates.

Features

• Sync Variables: Copy environment variables from one file to multiple targets
• Validation: Check for missing variables, empty values, and naming conventions
• Comparison: Compare two .env files to find differences
• Glob Support: Sync to multiple files using glob patterns
• Preserve Values: Keep existing values when syncing structure
• Generate Files: Create new .env files from .env.example templates
• Dry Run Mode: Preview changes before applying them

Quick Start

Installation

npm install -g env-file-manager

Or use directly with npx:

npx env-file-manager

Basic Usage

Validate an environment file:

env-file-manager validate .env

Compare two files:

env-file-manager compare .env.example .env

Sync variables across projects:

env-file-manager sync .env.example ../project-a/.env ../project-b/.env

Commands

validate

Validate an environment file for missing or empty variables.

env-file-manager validate <file> [options]

Options:

• -r, --required <keys...> - Required environment variable keys
• --allow-empty - Allow empty values (default: false)

Examples:

# Basic validation
env-file-manager validate .env

# Check for required variables
env-file-manager validate .env --required DATABASE_URL API_KEY

# Allow empty values
env-file-manager validate .env --allow-empty

compare

Compare two environment files to find missing or extra variables.

env-file-manager compare <source> <target>

Example:

env-file-manager compare .env.example .env

Output:

Comparing:
  .env.example
  .env

⚠ Differences found:

Missing in target:
  - NEW_API_KEY
  - FEATURE_FLAG

Extra in target:
  + OLD_DEPRECATED_VAR

sync

Sync environment variables from a source file to one or more target files.

env-file-manager sync <source> <targets...> [options]

Options:

• --overwrite - Overwrite existing values (default: false)
• --no-preserve-values - Don't preserve existing values in targets
• --no-merge-comments - Don't merge comments from targets
• --dry-run - Preview changes without writing files

Examples:

# Sync to a single file
env-file-manager sync .env.example .env

# Sync to multiple files
env-file-manager sync .env.example ../project-a/.env ../project-b/.env

# Sync using glob pattern
env-file-manager sync .env.example "../*/env"

# Preview changes (dry run)
env-file-manager sync .env.example .env --dry-run

# Overwrite existing values
env-file-manager sync .env.example .env --overwrite

Behavior:

• By default, syncs structure (keys) but preserves existing values
• Adds missing variables from source
• Preserves extra variables in target (unless --no-preserve-values)
• Merges comments from both files (unless --no-merge-comments)

list

List all variables in an environment file.

env-file-manager list <file> [options]

Options:

• --values - Show actual values (default: hidden)

Examples:

# List variables (values hidden)
env-file-manager list .env

# Show values
env-file-manager list .env --values

generate

Generate a new .env file from a .env.example template.

env-file-manager generate <example> <output> [options]

Options:

• --overwrite - Overwrite existing file (default: false)

Examples:

# Generate new .env file
env-file-manager generate .env.example .env

# Overwrite existing file
env-file-manager generate .env.example .env --overwrite

Use Cases

Onboarding New Developers

Generate a clean .env file for new team members:

env-file-manager generate .env.example .env

Keeping Multiple Projects in Sync

Sync shared environment variables across microservices:

env-file-manager sync shared.env "../service-*/env"

CI/CD Validation

Validate required variables in CI:

env-file-manager validate .env --required DATABASE_URL API_KEY SECRET_KEY

Pre-Deployment Checks

Compare staging and production configurations:

env-file-manager compare .env.staging .env.production

Upgrading Environment Files

When you add new variables to .env.example, sync them to existing files:

env-file-manager sync .env.example .env --dry-run
env-file-manager sync .env.example .env

File Format

The tool supports standard .env file format:

# Database configuration
DATABASE_URL=postgresql://localhost:5432/db

# API Keys
API_KEY=your-key-here
SECRET_KEY=your-secret

# Features
ENABLE_FEATURE_X=true

Conventions:

• Variable names should be UPPERCASE with underscores
• Comments start with #
• Values with spaces or special characters are automatically quoted

Tech Stack

• Commander.js: CLI framework
• Chalk: Colorful terminal output
• Glob: Pattern matching for multiple files
• TypeScript: Type-safe development

Development

Clone and install:

git clone https://github.com/patrickboxfordpartners/env-file-manager.git
cd env-file-manager
npm install

Build:

npm run build

Run in development:

npm run dev -- validate .env

License

MIT