hostfile

README

hostfile

繁體中文 | 日本語 | 한국어

A cross-platform CLI tool for managing your hosts file with ease.

Designed to be simple enough that anyone can use it — just copy-paste a command and hit Enter.

Features

• Add / Remove — manage IP-domain mappings, auto-merge same IP entries
• Enable / Disable — toggle entries without deleting them (per-IP or per-domain granularity)
• Search / Show — query and display managed entries with colored, aligned output
• Apply / Merge — import from files or stdin, auto-detects JSON and hosts format with validation
• JSON I/O — show --json for export, apply - / merge - for import via pipeline
• Save / Load — snapshot and restore your managed entries
• Clean — clear all managed entries in one command
• Managed block isolation — never modifies entries you wrote by hand
• Automatic privilege escalation (sudo / doas / gsudo)
• IPv4 + IPv6 support (including zone IDs)
• Shell completion (bash, zsh, fish, powershell)
• Cross-platform: macOS, Linux, Windows

How It Works

hostfile only touches its own managed block inside your hosts file — it never modifies entries you wrote by hand:

# Your original content — hostfile won't touch this
127.0.0.1  localhost

#### hostfile >>>>>
192.168.1.100  web.company.local api.company.local
#[disable-ip] 192.168.1.200  minio.company.local
#[disable-domain] dockerhand.company.local 192.168.1.100
#### hostfile <<<<<

Installation

Quick Install

macOS / Linux / Git Bash:

curl -fsSL https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.ps1 | iex

To update, run the same command again. To uninstall:

curl -fsSL https://raw.githubusercontent.com/vulcanshen/hostfile/main/uninstall.sh | sh

irm https://raw.githubusercontent.com/vulcanshen/hostfile/main/uninstall.ps1 | iex

Windows Note: hostfile modifies the system hosts file, which requires administrator privileges. On Windows 11 24H2+, sudo is built-in and hostfile will use it automatically. On older versions, install gsudo or run PowerShell as Administrator.

Install gsudo:

# PowerShell one-liner
irm https://raw.githubusercontent.com/gerardog/gsudo/master/installgsudo.ps1 | iex

# Or via Scoop
scoop install gsudo

Package Managers

Platform	Command
Homebrew (macOS / Linux)	brew install vulcanshen/tap/hostfile
Scoop (Windows)	scoop bucket add vulcanshen https://github.com/vulcanshen/scoop-bucket && scoop install hostfile
Debian / Ubuntu	sudo dpkg -i hostfile_<version>_linux_amd64.deb
RHEL / Fedora	sudo rpm -i hostfile_<version>_linux_amd64.rpm

.deb and .rpm packages can be downloaded from the Releases page. Replace <version> with the version number (e.g. 1.2.0). For ARM64 systems, use linux_arm64 instead of linux_amd64.

Commands

Command	Description
init	Take over the current hosts file — backs up as "origin", reformats all entries into managed block
add <ip> <domain1> [domain2...]	Add domains to an IP, auto-merge if the IP already exists
remove <ip|domain>	Remove an IP (entire line) or a single domain
search <ip|domain>	Fuzzy search the managed block — case-insensitive substring matching with highlighted results
show	Show all entries in the managed block (colored, aligned)
show --json	Output active entries as JSON
show <name>	Show the contents of a saved snapshot
enable <ip|domain>	Re-enable a disabled entry
disable <ip|domain>	Disable an entry without deleting it
apply <file | ->	Replace the managed block with content from a file or stdin (supports JSON)
merge <file | ->	Merge content from a file or stdin into the managed block (supports JSON)
clean	Clear all entries from the managed block
save <name>	Save the managed block as a snapshot to ~/.hostfile/<name>.hostfile
list	List all saved snapshots
load <name>	Load a saved snapshot into the managed block
delete <name>	Delete a saved snapshot
open	Open the hosts file in your default editor ($EDITOR, falls back to vi; Windows uses notepad)
version	Print the version number

Global Flags

Flag	Description
--hosts-file <path>	Path to hosts file (default: /etc/hosts or C:\Windows\System32\drivers\etc\hosts)

Show Flags

Flag	Description
--json	Output active entries as JSON ({"ip": ["domain1", "domain2"]})
--all	Include entries outside the managed block

Search Flags

Flag	Description
--all	Include entries outside the managed block

Usage Examples

# First time setup — take over your existing hosts file
hostfile init

# Add entries
hostfile add 192.168.1.100 web.local api.local

# Show managed entries
hostfile show
hostfile show --json            # JSON output (active only)

# Search
hostfile search web.local
hostfile search 192.168.1.100

# Disable / Enable
hostfile disable web.local        # disable a single domain
hostfile disable 192.168.1.100    # disable an entire IP line
hostfile enable web.local

# Remove
hostfile remove web.local          # remove a domain
hostfile remove 192.168.1.100     # remove an IP and all its domains

# Import from file
hostfile apply hosts.txt           # replace managed block
hostfile merge hosts.txt           # merge into managed block

# Import from JSON
hostfile apply config.json         # auto-detects JSON format
hostfile show --json | hostfile apply -  # pipe between instances

# Save / Load
hostfile save my-snapshot
hostfile list
hostfile show my-snapshot
hostfile load my-snapshot
hostfile delete my-snapshot

# Clear everything
hostfile clean

# Restore original hosts file (before init)
hostfile load origin

# Use a custom hosts file (for testing or dry-run)
hostfile show --hosts-file /tmp/test.hosts

Real-world scenarios

Field engineers switching between network environments

FAEs and consultants often work across multiple sites — company office, customer on-site, home. Each environment has different internal domains. On Windows, changing DNS adapter settings is buried and limited to two entries. Re-doing it every time you switch is error-prone and tedious.

The hosts file is the most portable solution. With hostfile:

Leaving for customer site

hostfile save company     # snapshot your office setup
hostfile clean            # clear everything

Back at the office

hostfile load company     # restore in one command

Keeping your machine clean

Instead of hardcoding internal IPs into your network settings, manage everything through hostfile. Enable what you need, disable what you don't. Your hand-written entries are never touched.

Sharing configs across a team

hostfile show --json | ssh teammate hostfile apply -

One pipeline to sync your hosts setup to another machine.

Shell Completion

# Zsh
mkdir -p ~/.zsh/completions
hostfile completion zsh > ~/.zsh/completions/_hostfile
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

# Bash
hostfile completion bash > /etc/bash_completion.d/hostfile

# Fish
hostfile completion fish > ~/.config/fish/completions/hostfile.fish

# PowerShell
hostfile completion powershell > hostfile.ps1

Advanced

Environment Variable	Description
HOSTFILE__HOSTS_FILE	Override the default hosts file path. When set, all commands use this path instead of /etc/hosts.
EDITOR	Editor used by open command. Falls back to vi on macOS/Linux, notepad on Windows.

License

GPL-3.0