DEV Community

Vulcan Shen
Vulcan Shen

Posted on • Edited on

I built a CLI to stop explaining what /etc/hosts is

#go #cli #devops #opensource

Last month, a PM asked me to point api.staging.local to a new IP. I spent 15 minutes explaining what /etc/hosts is. Then I did it for them anyway.

This happens a lot. So I built hostfile — a CLI that turns hosts file management into copy-pasteable one-liners.

demo

What's wrong with existing tools

Manual editing is risky. One wrong move and DNS resolution breaks. Non-technical users shouldn't be anywhere near vim /etc/hosts.

GUI tools like SwitchHosts exist, but they're overkill when you just need someone to run one command. You can't paste a GUI into Slack.

Other CLIs exist and work fine for developers who know what they're doing. But when you need a non-technical person to run one command without supervision, most fall apart.

What hostfile does differently

Managed block isolation. hostfile only touches entries between its own markers. Your hand-written entries are never modified:

# Your stuff — safe
127.0.0.1  localhost

#### hostfile >>>>>
192.168.1.100  web.local api.local
#### hostfile <<<<<
Enter fullscreen mode Exit fullscreen mode

Enable/disable without deleting. Need to temporarily turn off an entry? hostfile disable api.local. Turn it back on with hostfile enable api.local. No re-typing IPs.

JSON I/O and pipelines. Export your config as JSON, pipe it to another machine, or feed it into scripts:

# Export
hostfile show --json
# {"192.168.1.100": ["web.local", "api.local"]}

# Import via pipeline
echo '{"10.0.0.1":["db.local"]}' | hostfile merge -

# Sync between machines
hostfile show --json | ssh prod hostfile apply -
Enter fullscreen mode Exit fullscreen mode

Automatic privilege escalation. hostfile handles sudo, doas, or gsudo on Windows automatically. Users never need to remember.

Input validation. Bad JSON, invalid IPs, or garbage text gets rejected before touching your hosts file.

Quick start 

# Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.sh | sh

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

# Save a snapshot before making changes
hostfile save before-migration

# Roll back if needed
hostfile load before-migration

# Done with this setup
hostfile clean
Enter fullscreen mode Exit fullscreen mode

Install 

# macOS / Linux
brew install vulcanshen/tap/hostfile

# Windows
irm https://raw.githubusercontent.com/vulcanshen/hostfile/main/install.ps1 | iex
Enter fullscreen mode Exit fullscreen mode

Also available as .deb, .rpm, and Scoop. See the README for all options.

Real-world use case: Field engineers on customer sites

The PM story is real, but here's an even more common scenario:
field engineers (FAE) and consultants who work across multiple
network environments.

When you're on-site at a customer, you need their internal
domains to resolve correctly. When you're back at the office,
you need your company's internal domains. On Windows, this is
painful — the network adapter DNS settings are buried deep in
the UI, limited to two entries, and you have to redo everything
every single time you switch environments.

The hosts file is actually the most portable solution. With
hostfile, the workflow becomes:

Leaving for customer site

hostfile save company # snapshot your current setup
hostfile clean # clear everything, use customer DNS

Back at the office

hostfile load company # restore in one command

No more digging through network adapter settings. No more
forgetting to reset DNS before connecting to company VPN.
Just two commands.

This isn't a revolutionary tool. It solves one specific problem: making hosts file changes safe and accessible to anyone who can copy-paste a command. If that's a problem you have, give it a try.

GitHub: vulcanshen/hostfile

Top comments (0)