EnvSwitch

A fast, reliable command-line tool for managing and switching environment variable configurations. Built with Rust for performance and safety.

Features

• 🚀 Fast Configuration Switching: Instantly switch between different environment variable sets
• 🐚 Multi-Shell Support: Works with zsh, fish, bash, and other shells
• 💾 Persistent Storage: Configurations are saved locally and persist across sessions
• 🔒 Safe Operations: Built-in validation prevents invalid configurations
• 📦 Import/Export: Share configurations between machines or backup your settings
• 🎯 Claude AI Integration: Optimized for switching between different AI model configurations

Installation

From Source

git clone https://github.com/soddygo/envswitch
cd envswitch
cargo build --release
cp target/release/envswitch /usr/local/bin/

Using Cargo

cargo install --git https://github.com/soddygo/envswitch

Quick Start

1. Create your first configuration

# Create a configuration for DeepSeek AI
envswitch set deepseek \
  -e ANTHROPIC_BASE_URL=https://api.deepseek.com \
  -e ANTHROPIC_MODEL=deepseek-chat \
  -e ANTHROPIC_AUTH_TOKEN=sk-your-deepseek-token

# Create a configuration for Kimi AI
envswitch set kimi \
  -e ANTHROPIC_BASE_URL=https://api.moonshot.cn \
  -e ANTHROPIC_MODEL=moonshot-v1-8k \
  -e ANTHROPIC_AUTH_TOKEN=sk-your-kimi-token

2. Install shell integration (recommended)

# Install shell integration for seamless usage
./install-shell-integration.sh

# Restart your shell or source your config
source ~/.zshrc  # or ~/.bashrc, ~/.config/fish/config.fish

3. Switch between configurations

# With shell integration (no eval needed!)
envswitch use deepseek
envswitch use kimi

# Or use short aliases
esu deepseek
esu kimi

# Interactive selector
esw

# Without shell integration (traditional way)
eval "$(envswitch use deepseek)"
eval "$(envswitch use kimi)"

4. View your configurations

# List all configurations
envswitch list

# Show current active configuration and environment variables
envswitch status

Shell Integration

🚀 Easy Setup (Recommended)

For the best experience, install our shell integration that eliminates the need for eval:

# Run the installer
./install-shell-integration.sh

# Restart your shell or source your config file
source ~/.zshrc  # for zsh
source ~/.bashrc # for bash
source ~/.config/fish/config.fish # for fish

After installation, you can use envswitch directly:

# No more eval needed! 🎉
envswitch use deepseek    # Direct switch
esu kimi                 # Short alias
esw                      # Interactive selector
esq myconfig             # Quick create from current environment

Manual Shell Integration

If you prefer manual setup, add these aliases to your shell configuration:

Zsh (~/.zshrc)

alias switch-deepseek='eval "$(envswitch use deepseek)"'
alias switch-kimi='eval "$(envswitch use kimi)"'
alias envs='envswitch list'
alias envstatus='envswitch status'

Fish (~/.config/fish/config.fish)

alias switch-deepseek='eval (envswitch use deepseek)'
alias switch-kimi='eval (envswitch use kimi)'
alias envs='envswitch list'
alias envstatus='envswitch status'

Bash (~/.bashrc)

alias switch-deepseek='eval "$(envswitch use deepseek)"'
alias switch-kimi='eval "$(envswitch use kimi)"'
alias envs='envswitch list'
alias envstatus='envswitch status'

Commands

Configuration Management

# Create or update a configuration
envswitch set <alias> -e KEY1=value1 -e KEY2=value2

# List all configurations
envswitch list

# Show detailed information about a configuration
envswitch show <alias>

# Delete a configuration
envswitch delete <alias>

# Edit a configuration interactively
envswitch edit <alias>

Environment Switching

# Switch to a configuration (generates shell commands)
envswitch use <alias>

# Show current environment status
envswitch status

# Clear environment variables
envswitch clear

Import/Export

# Export all configurations to JSON (default format)
envswitch export -o configs.json

# Export with metadata and pretty formatting
envswitch export -o configs.json --metadata --pretty

# Export specific configurations
envswitch export -c deepseek,kimi -o my-ai-configs.json

# Export in different formats
envswitch export -o configs.env --format env
envswitch export -o configs.yaml --format yaml

# Import configurations from a file
envswitch import configs.json

# Import with backup (creates backup before importing)
envswitch import configs.json --backup

# Import with conflict resolution
envswitch import configs.json --force    # Overwrite existing
envswitch import configs.json --merge    # Merge with existing

# Preview import without making changes
envswitch import configs.json --dry-run

# Import from different formats (auto-detected)
envswitch import configs.env
envswitch import configs.yaml

Configuration Examples

AI Model Configurations

# OpenAI GPT-4
envswitch set openai \
  -e OPENAI_API_KEY=sk-your-openai-key \
  -e OPENAI_MODEL=gpt-4 \
  -e OPENAI_BASE_URL=https://api.openai.com/v1

# Anthropic Claude
envswitch set claude \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  -e ANTHROPIC_MODEL=claude-3-sonnet-20240229 \
  -e ANTHROPIC_BASE_URL=https://api.anthropic.com

# Local development
envswitch set local \
  -e DATABASE_URL=postgresql://localhost:5432/myapp_dev \
  -e REDIS_URL=redis://localhost:6379 \
  -e DEBUG=true \
  -e LOG_LEVEL=debug

# Production
envswitch set prod \
  -e DATABASE_URL=postgresql://prod-db:5432/myapp \
  -e REDIS_URL=redis://prod-redis:6379 \
  -e DEBUG=false \
  -e LOG_LEVEL=info

Advanced Usage

Conditional Configurations

# Create configurations with descriptions
envswitch set staging \
  -e API_URL=https://staging-api.example.com \
  -e DEBUG=true \
  --description "Staging environment configuration"

Backup and Restore

# Create a backup of all configurations
envswitch export -o backup-$(date +%Y%m%d).json --metadata --pretty

# Restore from backup with merge
envswitch import backup-20241201.json --merge --backup

# Force restore (overwrites existing configurations)
envswitch import backup-20241201.json --force

# Preview what would be restored
envswitch import backup-20241201.json --dry-run

Interactive Configuration Editing

# Edit a configuration interactively
envswitch edit myconfig

# The interactive editor allows you to:
# - Add new environment variables
# - Edit existing variables
# - Delete variables
# - Update configuration description
# - Save or cancel changes

Advanced Export/Import Options

# Export with verbose output
envswitch export -o configs.json --verbose

# Export only specific configurations with metadata
envswitch export -c prod,staging -o prod-configs.json --metadata --pretty

# Import with validation and backup
envswitch import configs.json --backup --verbose

# Cross-format conversion (export JSON, import as ENV)
envswitch export -o temp.json --format json
envswitch import temp.json  # Auto-detects JSON format

Configuration File Location

Configurations are stored in:

• macOS/Linux: ~/.config/envswitch/config.json
• Windows: %APPDATA%\envswitch\config.json

FAQ

Why do I need eval "$(envswitch use config)" instead of just envswitch use config?

This is a technical limitation, not a design flaw. Here's why:

1. Subprocess limitation: When you run envswitch use config, it runs in a subprocess that cannot modify your current shell's environment variables.

2. Shell command generation: envswitch use config outputs shell commands like:

   export ANTHROPIC_BASE_URL='https://api.deepseek.com'
   export ANTHROPIC_MODEL='deepseek-chat'
   

3. eval executes commands: eval "$(envswitch use config)" makes your shell execute these export commands, setting the environment variables.

Solution: Use our shell integration! Run ./install-shell-integration.sh to enable direct usage:

envswitch use config  # No eval needed after integration!

How does the shell integration work?

The shell integration creates a wrapper function that:

1. Captures the output from envswitch use config
2. Automatically runs eval on the output
3. Provides a seamless experience

It's completely safe and just automates what you would do manually.

Troubleshooting

Common Issues

Configuration not found

envswitch list  # Check available configurations
# If you see suggestions, check for typos in the configuration name

Shell commands not working

# Make sure to use eval
eval "$(envswitch use myconfig)"

# Check your shell type
echo $SHELL

# For fish shell, use different syntax
eval (envswitch use myconfig)

Permission errors

# Check configuration directory permissions
ls -la ~/.config/envswitch/

# Fix permissions if needed
chmod 755 ~/.config/envswitch/
chmod 644 ~/.config/envswitch/config.json

Import/Export issues

# Check file format and content
envswitch import myfile.json --dry-run

# Use verbose mode for detailed error information
envswitch import myfile.json --verbose

# For corrupted files, check the format
file myfile.json  # Should show JSON data

Interactive editing problems

# If edit command doesn't work, check configuration exists
envswitch list

# Create new configuration if needed
envswitch edit newconfig  # Will offer to create new one

Large configuration performance

# For large configurations, use specific exports
envswitch export -c config1,config2 -o subset.json

# Use non-pretty format for faster processing
envswitch export -o configs.json  # Without --pretty flag

Getting Help

# Show help for all commands
envswitch --help

# Show help for a specific command
envswitch set --help

Development

Building from Source

git clone https://github.com/soddygo/envswitch
cd envswitch
cargo build --release

Running Tests

# Run all tests
cargo test

# Run specific test suites
cargo test --test integration_tests
cargo test --test shell_compatibility_tests
cargo test --test error_scenario_tests
cargo test --test missing_features_tests
cargo test --test command_workflow_tests

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_export_import_workflow

Project Structure

src/
├── main.rs              # Main entry point
├── cli.rs               # Command line interface
├── config.rs            # Configuration management
├── env.rs               # Environment variable handling
├── shell.rs             # Shell detection and command generation
├── error.rs             # Error types and handling
├── types.rs             # Common type definitions
├── commands/            # Command implementations
├── handlers/            # Utility handlers
└── utils/               # Utility functions

tests/
├── integration_tests.rs        # End-to-end workflow tests
├── shell_compatibility_tests.rs # Shell-specific tests
└── error_scenario_tests.rs     # Error handling tests

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (cargo test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

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

Acknowledgments

• Built with Rust for performance and safety
• Uses clap for command-line parsing
• Inspired by the need for easy AI model configuration switching