HostSwitch


A simple CLI tool for switching hosts file profiles

日本語

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.

$3

- 👨‍💻 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

$3

``bash

Global installation

npm install -g @milkmaccya2/hostswitch

Or run directly with npx

npx @milkmaccya2/hostswitch list
`

$3

`bash

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

$3

`bash

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
`

$3

`bash
hostswitch list

or

hostswitch ls
`

$3

`bash

Create with default content

hostswitch create development

Create from current hosts file

hostswitch create production --from-current
`

$3

`bash

No need to type sudo manually - it will automatically rerun with sudo if needed

hostswitch switch development

or

hostswitch use development
`

$3

`bash
hostswitch show development

or

hostswitch cat development
`

$3

`bash
hostswitch edit development
`

$3

`bash

Delete with confirmation flag (required for safety)

hostswitch delete development --force

or

hostswitch rm development --force
`

Common Use Cases

$3

`bash


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
`

$3

`bash


Reference team member's environment

hostswitch create team-dev --from-current

Switch back to your environment (auto-sudo)

hostswitch switch local
`

$3

`bash


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

$3

`bash

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
`

$3

The project uses Biome for linting and formatting:

`bash


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
`

$3

`bash

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
`

$3

`
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
`

$3

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

$3

#### Auto-sudo Detection
HostSwitch automatically detects when sudo privileges are needed and will prompt for admin access:

`bash


✅ 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
`bash


If auto-sudo fails, try manual sudo

sudo hostswitch switch dev

On Windows, run as Administrator

Right-click Command Prompt → "Run as administrator"

`

$3

#### Profile Not Found
`bash


Check available profiles

hostswitch list

Verify profile name (case-sensitive)

hostswitch show [profile-name]

Check profile directory

ls ~/.hostswitch/profiles/
`

#### Profile Corruption
`bash


Recreate corrupted profile


hostswitch delete corrupted-profile --force
hostswitch create corrupted-profile --from-current
`

$3

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.