CLI Reference

txeh provides a command-line interface for managing /etc/hosts file entries.

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/txeh

Go Install

Requires Go 1.24 or later.

go install github.com/txn2/txeh/txeh@latest

The binary is installed to $GOPATH/bin. Ensure this directory is in your $PATH.

Binary Download

Pre-built binaries are available on the GitHub Releases page:

.deb, .rpm, and .apk packages are also available for each release.

Build from Source

git clone https://github.com/txn2/txeh.git
cd txeh
go install ./txeh

Verify installation:

txeh version

Quick Start

# Add a hostname
sudo txeh add 127.0.0.1 myapp.local

# List hosts for an IP
txeh list ip 127.0.0.1

# Remove a hostname
sudo txeh remove host myapp.local

# Preview changes without saving
sudo txeh add 127.0.0.1 myapp.local --dryrun

Global Flags

Commands

add

Add one or more hostnames to an IP address.

sudo txeh add [IP] [HOSTNAME] [HOSTNAME]...

Flags:

Examples:

# Add a single hostname
sudo txeh add 127.0.0.1 myapp.local

# Add multiple hostnames
sudo txeh add 127.0.0.1 app1.local app2.local app3.local

# Add with a comment for organization
sudo txeh add 127.0.0.1 myapp.local --comment "dev environment"

# Preview without saving
sudo txeh add 127.0.0.1 myapp.local --dryrun

remove host

Remove one or more hostnames from the hosts file.

sudo txeh remove host [HOSTNAME] [HOSTNAME]...

sudo txeh remove host myapp.local
sudo txeh remove host app1.local app2.local

remove ip

Remove an IP address and all hostnames associated with it.

sudo txeh remove ip [IP] [IP]...

sudo txeh remove ip 127.0.0.1
sudo txeh remove ip 10.0.0.1 10.0.0.2

remove cidr

Remove all addresses within one or more CIDR ranges.

sudo txeh remove cidr [CIDR] [CIDR]...

sudo txeh remove cidr 10.0.0.0/24
sudo txeh remove cidr 192.168.1.0/24 172.16.0.0/12

# Preview with dry run
sudo txeh remove cidr 10.0.0.0/8 --dryrun

remove bycomment

Remove all host entries that have a specific inline comment.

sudo txeh remove bycomment [COMMENT]

sudo txeh remove bycomment "dev environment"
sudo txeh remove bycomment "kubefwd"

list ip

List hostnames associated with one or more IP addresses.

txeh list ip [IP] [IP]...

list cidr

List hostnames for all addresses within CIDR ranges.

txeh list cidr [CIDR] [CIDR]...

list host

List IP addresses associated with one or more hostnames.

txeh list host [HOSTNAME] [HOSTNAME]...

list bycomment

List all hosts that have a specific inline comment.

txeh list bycomment [COMMENT]

show

Display the full rendered hosts file.

txeh show

version

Print the txeh version.

txeh version

DNS Cache Flushing

The --flush (-f) flag triggers a DNS cache flush after writing the hosts file. This makes new entries resolve immediately without manual intervention.

sudo txeh add 127.0.0.1 myapp.local --flush

You can also set the TXEH_AUTO_FLUSH environment variable to always flush:

export TXEH_AUTO_FLUSH=1
sudo txeh add 127.0.0.1 myapp.local   # flush happens automatically

If the flush fails (e.g., the resolver binary is missing), the hosts file is still saved. txeh prints a warning to stderr and exits normally.

Platform Commands

txeh runs these OS-provided commands. Nothing extra needs to be installed.

Linux Without systemd-resolved

If your Linux system doesn't run systemd-resolved (common with dnsmasq, unbound, or no local caching), txeh prints a warning and exits normally. In this case, flushing isn't needed because DNS lookups go directly to /etc/hosts or to a remote resolver that doesn't cache your local entries.