txeh v1.8.0 · go /etc/hosts management.

txeh manages the /etc/hosts file from Go and from the shell. Add, remove, list, and query hostname-to-IP mappings without hand-editing. Mutex-protected for safe concurrent use, comment-aware so entries from different sources stay separable, and cross-platform across Linux, macOS, and Windows. The library powers kubefwd's per-service hostname resolution and ships as a standalone CLI.

IPv4 and IPv6, CIDR-based bulk add and remove, dry-run preview, optional DNS cache flush after writes, and an in-memory mode that operates on raw text instead of a file. Apache 2.0, originally built to support kubefwd for Kubernetes service forwarding.

§ 01 / install · run

Install. Then use it.

Install with brew, go install, or grab a release binary. Run the CLI with sudo so txeh can write /etc/hosts. Or import the Go library and manage hosts from a service, daemon, or test fixture.

CLI-001 · go · cli reference ↗

cli mode

Add, remove, list, and show entries from the shell.

One binary, no daemons. Add a single hostname, a comma-separated list, or remove a whole CIDR range. Use --dryrun to preview changes, --comment to tag entries by source, and --flush to refresh the DNS cache after writes.

~ / txeh

$ brew install txn2/tap/txeh
$ sudo txeh add 127.0.0.1 myapp.local
  + 127.0.0.1 myapp.local

$ txeh list ip 127.0.0.1
  localhost myapp.local

$ sudo txeh remove host myapp.local --dryrun
# preview only, no write

LIB-002 · go · library docs ↗

go library

Programmatic hosts file management. Thread-safe.

NewHostsDefault() finds the system hosts file and returns a mutex-protected handle. Call AddHost, RemoveHost, or RemoveCIDRs from any goroutine and Save() to write. Or pass RawText to operate on a string in-memory.

~ / library

$ go get github.com/txn2/txeh

// main.go
hosts, _ := txeh.NewHostsDefault()
hosts.AddHost("127.0.0.1", "myapp.local")
hosts.AddHostWithComment(
    "10.0.0.1", "db", "staging",
)
_ = hosts.Save()

§ 02 / what it does

Hosts file as data. Not a string to grep.

txeh parses the hosts file into a structured representation, mutates it through typed methods, and renders it back without losing comments or formatting.

001
add and remove by host, ip, or cidr
Single-host or bulk operations. AddHost, AddHosts, RemoveHost, RemoveAddress, RemoveCIDRs. Operations are idempotent; re-adding a hostname is a no-op.

core
002
thread-safe by default
All public methods take an internal mutex. Daemons, controllers, and tools that mutate hosts from multiple goroutines (kubefwd among them) can call them directly without external locking.

runtime
003
inline comments preserved
AddHostWithComment tags entries with a source string. RemoveByComment removes everything tagged with that source. The library re-renders the file without losing any comment or blank line.

format
004
query by host, ip, or comment
ListAddressesByHost, ListHostsByIP, ListHostsByComment, ListHostsByCIDR. Read-only inspection without parsing or rewriting.

query
005
dns cache flush
--flush on the CLI or TXEH_AUTO_FLUSH=1 in the environment runs the OS-native flush command after writes. dscacheutil on macOS, resolvectl on Linux, ipconfig /flushdns on Windows.

dns
006
in-memory mode for tests
Pass RawText to NewHosts and operate on a string. Save() errors as expected (no path); RenderHostsFile() returns the mutated text. Useful in unit tests and ephemeral fixtures.

testing
···
ipv4 and ipv6, custom paths, dry-run, version stamping
Full type and method reference in the API docs.

+ more

// open source

txeh is one of several open source components by Craig Johnston, sponsored by Deasil Works, Inc. and Plexara. Released under the Apache 2.0 license. Originally built to support kubefwd for Kubernetes service forwarding.

github.com/txn2/txeh → txn2.com ↗ pkg.go.dev ↗ releases ↗