npm package: @sagar-tarak/envswitch
Description: A powerful CLI tool for switching between different environment configurations with a single command
Author: EnvSwitch Team
Latest version: 1.0.0

# EnvSwitch

[![npm version](https://badge.fury.io/js/envswitch.svg)](https://badge.fury.io/js/envswitch)
[![npm downloads](https://img.shields.io/npm/dm/envswitch.svg)](https://www.npmjs.com/package/envswitch)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/envswitch.svg)](https://nodejs.org/)
[![Build Status](https://github.com/envswitch/envswitch/workflows/CI/badge.svg)](https://github.com/envswitch/envswitch/actions)

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)
```bash
npm install -g envswitch
```

### Local Installation
```bash
npm install --save-dev envswitch
```

### From Source
```bash
git clone https://github.com/envswitch/envswitch.git
cd envswitch
npm install
npm link  # Makes envswitch available globally
```

## 🎯 Quick Start

### 1. Initialize Configuration
```bash
# Interactive setup
envswitch init

# Quick setup with basic template
envswitch init --yes

# Use full template
envswitch init --template full
```

### 2. Switch Environments
```bash
# 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
```bash
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:

```json
{
  "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
```bash
# 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
```bash
# Show detailed environment information
envswitch list --verbose
```

### JSON Status Output
```bash
# Get status in JSON format for scripting
envswitch status --json
```

### Configuration Validation
```bash
# Validate your configuration file
envswitch validate
```

### Force Environment Switch
```bash
# 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"**
```bash
envswitch init
```

**"Environment not found"**
```bash
envswitch list  # Check available environments
```

**Permission errors**
```bash
# Ensure write permissions in project directory
chmod 755 .
```

**Invalid configuration**
```bash
envswitch validate  # Check for configuration issues
```

### Getting Help
```bash
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:

```bash
# 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
```bash
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](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/envswitch/envswitch/issues)
- **Documentation**: [GitHub Wiki](https://github.com/envswitch/envswitch/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/envswitch/envswitch/discussions)
- **Security**: [Security Policy](https://github.com/envswitch/envswitch/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](https://www.npmjs.com/package/envswitch)
- **Stars**: [GitHub stars](https://github.com/envswitch/envswitch/stargazers)
- **Forks**: [GitHub forks](https://github.com/envswitch/envswitch/network/members)

---

**Made with ❤️ for developers who hate manual environment switching**

*Built with Node.js, Commander.js, and Inquirer.js*