HostSwitch

A simple CLI tool for switching hosts file profiles

日本語 | Documentation (English) | Documentation (日本語)

Overview

HostSwitch is a CLI tool that makes it easy to switch between different hosts configurations for development and testing environments. Unlike GUI applications like Gas Mask, it focuses on quick command-line operations.

Perfect for

• 👨‍💻 Web developers working with multiple development environments
• 🔧 Engineers who need to test across local, staging, and production
• 🏢 System administrators managing multiple server environments
• 🚀 Anyone who prefers fast CLI operations

Key Features

• ✅ Multiple hosts profile management - For development, staging, production, etc.
• 💾 Automatic backup - Saves current hosts before switching
• 🎨 Colorful output - Clear status visibility
• ⚡ Simple CLI - Easy-to-remember commands
• 🔒 Safe operations - Explicit sudo requirements
• 🎯 Interactive mode - User-friendly prompts when run without arguments

Requirements

• Node.js 20.0.0 or higher
• macOS / Linux / Windows (WSL recommended)
• sudo permissions (for hosts file switching)

Installation

Install from npm (Recommended)

# Global installation
npm install -g @milkmaccya2/hostswitch

# Or run directly with npx
npx @milkmaccya2/hostswitch list

Install from source

# Clone repository
git clone https://github.com/milkmaccya2/hostswitch.git
cd hostswitch

# Install dependencies
npm install

# Build TypeScript source
npm run build

# Global installation (optional)
npm link

Usage

Interactive Mode

# Run without arguments for interactive mode
hostswitch

# Navigate with arrow keys, select options with Enter
? What would you like to do? (Use arrow keys)
❯ Switch profile (current: local)
  List all profiles  
  Create new profile
  Edit profile
  Delete profile
  Exit

List profiles

hostswitch list
# or
hostswitch ls

Create a profile

# Create with default content
hostswitch create development

# Create from current hosts file
hostswitch create production --from-current

Switch profile (auto-sudo)

# No need to type sudo manually - it will automatically rerun with sudo if needed
hostswitch switch development
# or
hostswitch use development

Show profile contents

hostswitch show development
# or
hostswitch cat development

Edit a profile

hostswitch edit development

Delete a profile

# Delete with confirmation flag (required for safety)
hostswitch delete development --force
# or
hostswitch rm development --force

Common Use Cases

Development Environment Setup

# For local development
hostswitch create local
hostswitch edit local
# 127.0.0.1 api.myapp.local
# 127.0.0.1 app.myapp.local

# For Docker environment
hostswitch create docker
hostswitch edit docker
# 172.17.0.2 api.myapp.docker
# 172.17.0.3 db.myapp.docker

# Switch between them (auto-sudo)
hostswitch switch local

Team Development

# Reference team member's environment
hostswitch create team-dev --from-current

# Switch back to your environment (auto-sudo)
hostswitch switch local

Production Testing

# Create hosts pointing to production
hostswitch create production
hostswitch edit production
# 192.168.1.100 api.myapp.com
# 192.168.1.101 app.myapp.com

# Run tests (auto-sudo)
hostswitch switch production
# After testing (auto-sudo)
hostswitch switch local

Development

Building from source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run build:watch

# Run in development mode
npm run dev -- list

Code Quality

The project uses Biome for linting and formatting:

# Check for linting errors
npm run lint

# Auto-fix linting and formatting issues
npm run lint:fix

# Format code only
npm run format

# Check formatting without fixing
npm run format:check

# Run linting + formatting + tests (recommended for CI)
npm run check

Testing

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Open test UI
npm run test:ui

# Generate coverage report
npm run test:coverage

Project Structure

hostswitch/
├── src/
│   ├── interfaces/           # Type definitions and abstractions
│   ├── core/                # Domain logic (business rules)
│   ├── cli/                 # CLI-specific implementation
│   ├── infrastructure/      # External dependencies implementation
│   ├── config/              # Configuration management
│   └── hostswitch.ts       # Entry point with dependency injection
├── dist/                    # Compiled JavaScript (generated)
├── tsconfig.json           # TypeScript configuration
└── package.json

Architecture

The application follows a clean architecture pattern:

• Domain Layer: Pure business logic in HostSwitchService
• CLI Layer: Command handling and user interaction
• Infrastructure Layer: File system, logging, and process execution
• Dependency Injection: All dependencies are injected via interfaces

This design enables:

• Easy unit testing with mocked dependencies
• Clear separation of concerns
• Platform-agnostic core logic
• Future extensibility (e.g., GUI or API interfaces)

Troubleshooting

Permission Issues

Auto-sudo Detection

HostSwitch automatically detects when sudo privileges are needed and will prompt for admin access:

# ✅ Recommended - HostSwitch handles sudo automatically
hostswitch switch dev
# → "Requesting administrative access..." (auto-sudo prompt)

# ✅ Manual sudo also works
sudo hostswitch switch dev

# ❌ Will show auto-sudo prompt if permissions needed
hostswitch switch dev  # Auto-prompts for sudo

Permission Denied Errors

# If auto-sudo fails, try manual sudo
sudo hostswitch switch dev

# On Windows, run as Administrator
# Right-click Command Prompt → "Run as administrator"

Profile Issues

Profile Not Found

# Check available profiles
hostswitch list

# Verify profile name (case-sensitive)
hostswitch show [profile-name]

# Check profile directory
ls ~/.hostswitch/profiles/

Profile Corruption

# Recreate corrupted profile
hostswitch delete corrupted-profile --force
hostswitch create corrupted-profile --from-current

Windows Usage

For Windows, we recommend using WSL (Windows Subsystem for Linux). If using native Windows, run Command Prompt as Administrator.

Note: Native Windows support has been improved. The tool now automatically detects the Windows hosts file location (C:\Windows\System32\drivers\etc\hosts).

Data Storage

• Profiles: ~/.hostswitch/profiles/
• Backups: ~/.hostswitch/backups/
• Current profile info: ~/.hostswitch/current.json

License

MIT License - See LICENSE file for details.

Author

milkmaccya2

Contributing

Bug reports and feature requests are welcome at GitHub Issues.