EnvSwitch

A powerful CLI tool for switching between different environment configurations with a single command. Perfect for developers working across multiple environments (local, development, staging, production).

🚀 Features

• Single Command Switching: Switch environments with envswitch use <env>
• Interactive Mode: User-friendly prompts for environment selection
• Automatic Backup: Safely backs up your current .env file before switching
• Configuration Management: Easy setup and management of environment variables
• Cross-Platform: Works on Windows, macOS, and Linux
• Project Detection: Automatically finds your project root directory
• Template Support: Pre-built templates for quick setup
• Validation: Built-in configuration validation and error checking

📦 Installation

Global Installation (Recommended)

npm install -g envswitch

Local Installation

npm install --save-dev envswitch

From Source

git clone https://github.com/envswitch/envswitch.git
cd envswitch
npm install
npm link  # Makes envswitch available globally

🎯 Quick Start

1. Initialize Configuration

# Interactive setup
envswitch init

# Quick setup with basic template
envswitch init --yes

# Use full template
envswitch init --template full

2. Switch Environments

# Switch to development environment
envswitch use dev

# Switch to production environment
envswitch use production

# Switch to local environment
envswitch use local

# Force switch without confirmation
envswitch use dev --force

3. Interactive Mode

envswitch

Run without arguments to get an interactive prompt for environment selection.

📋 Commands

| Command | Description | Options | |---------|-------------|---------| | envswitch use <env> | Switch to a specific environment | -f, --force | | envswitch list | List all available environments | -v, --verbose | | envswitch status | Show currently active environment | -j, --json | | envswitch init | Initialize configuration file | -y, --yes, -t, --template | | envswitch validate | Validate configuration file | | | envswitch | Interactive mode (default) | |

⚙️ Configuration

The tool uses a envswitch.config.json file in your project root. Here's an example:

{
  "local": {
    "API_URL": "http://localhost:3000",
    "DB_URL": "mongodb://localhost:27017",
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug",
    "REDIS_URL": "redis://localhost:6379"
  },
  "dev": {
    "API_URL": "https://dev-api.company.com",
    "DB_URL": "mongodb://dev-db.company.com:27017",
    "NODE_ENV": "development",
    "LOG_LEVEL": "info",
    "REDIS_URL": "redis://dev-redis.company.com:6379"
  },
  "staging": {
    "API_URL": "https://staging-api.company.com",
    "DB_URL": "mongodb://staging-db.company.com:27017",
    "NODE_ENV": "staging",
    "LOG_LEVEL": "warn",
    "REDIS_URL": "redis://staging-redis.company.com:6379"
  },
  "production": {
    "API_URL": "https://api.company.com",
    "DB_URL": "mongodb://prod-db.company.com:27017",
    "NODE_ENV": "production",
    "LOG_LEVEL": "error",
    "REDIS_URL": "redis://prod-redis.company.com:6379"
  }
}

🔄 How It Works

1. Configuration Loading: Reads environment variables from envswitch.config.json
2. Validation: Ensures the requested environment exists and config is valid
3. Backup Creation: Safely backs up current .env to .env.backup
4. Environment Switch: Writes new environment variables to .env
5. Metadata Update: Stores switching information in .envswitch.metadata
6. Confirmation: Provides clear feedback on successful switch

📁 File Structure

your-project/
├── .env                          # Current environment variables
├── .env.backup                  # Backup of previous .env
├── .envswitch.metadata         # Tool metadata
├── envswitch.config.json       # Environment configurations
└── package.json

🛠️ Advanced Usage

Template Configuration

# Use basic template (local environment only)
envswitch init --template basic

# Use full template (local, dev, production)
envswitch init --template full

# Custom setup with prompts
envswitch init

Verbose Environment Listing

# Show detailed environment information
envswitch list --verbose

JSON Status Output

# Get status in JSON format for scripting
envswitch status --json

Configuration Validation

# Validate your configuration file
envswitch validate

Force Environment Switch

# Skip confirmation prompts
envswitch use production --force

🔒 Security Considerations

• Never commit sensitive data like API keys or passwords to version control
• Use environment-specific secrets for production environments
• Consider using .gitignore for your .env files
• Backup files are created automatically but may contain sensitive information
• Validate configurations before switching to production environments

🐛 Troubleshooting

Common Issues

"Configuration file not found"

envswitch init

"Environment not found"

envswitch list  # Check available environments

Permission errors

# Ensure write permissions in project directory
chmod 755 .

Invalid configuration

envswitch validate  # Check for configuration issues

Getting Help

envswitch --help          # Show all commands
envswitch use --help      # Show command-specific help
envswitch --version       # Show version information

🧪 Testing

Run the test suite to ensure everything works correctly:

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/envswitch/envswitch.git
cd envswitch
npm install
npm link
npm test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions
• Security: Security Policy

🔮 Roadmap

• [ ] YAML configuration support
• [ ] Environment variable validation
• [ ] Pre/post switch hooks
• [ ] Cloud secret integration (AWS, Azure, GCP)
• [ ] Team configuration sharing
• [ ] CI/CD integration
• [ ] Environment comparison tools
• [ ] Migration utilities

📊 Statistics

• Downloads: npm stats
• Stars: GitHub stars
• Forks: GitHub forks

Made with ❤️ for developers who hate manual environment switching

Built with Node.js, Commander.js, and Inquirer.js