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
• 🔄 DNS cache flush - Flushes the OS DNS cache after switching, so changes take effect immediately
• 🎨 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 once (watch is disabled in vite.config.ts)
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

Status

hostswitch status

Shows the active profile, whether /etc/hosts still matches it (in sync vs modified outside hostswitch), when you last switched, and the most recent backup.

Backups

Every switch backs up your current hosts file under ~/.hostswitch/backups/. List and restore them:

hostswitch backups          # list available backups, newest first
hostswitch restore          # restore the most recent backup (requires sudo)
hostswitch restore <id>     # restore a specific backup

The most recent 20 backups are kept; older ones are pruned automatically. Restoring clears the active profile, since a restored hosts file may not match any profile.

Contributing

Bug reports and feature requests are welcome at GitHub Issues. See CONTRIBUTING.md for setup, development workflow, and testing guidelines.

Update Notifications

hostswitch checks for a newer published version at most once a day. To turn it off:

export HOSTSWITCH_NO_UPDATE_CHECK=true

The check is also skipped automatically while running as root, so sudo hostswitch switch never leaves a root-owned config file behind.

Security

Found a security issue? Please see SECURITY.md for how to report it privately.