CLI Reference¶
txeh provides a command-line interface for managing /etc/hosts file entries.
Installation¶
Requires Go 1.24 or later.
The binary is installed to $GOPATH/bin. Ensure this directory is in your $PATH.
Pre-built binaries are available on the GitHub Releases page:
| OS | Architectures |
|---|---|
| Linux | amd64, arm64, arm, 386 |
| macOS | amd64 (Intel), arm64 (Apple Silicon) |
| Windows | amd64, 386 |
.deb, .rpm, and .apk packages are also available for each release.
Verify installation:
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¶
| Flag | Short | Description |
|---|---|---|
--dryrun |
-d |
Output to stdout without saving |
--quiet |
-q |
Suppress output |
--read |
-r |
Override path to read hosts file |
--write |
-w |
Override path to write hosts file |
--flush |
-f |
Flush DNS cache after modifying the hosts file |
--max-hosts-per-line |
-m |
Max hostnames per line (0=auto, -1=unlimited) |
Commands¶
add¶
Add one or more hostnames to an IP address.
Flags:
| Flag | Short | Description |
|---|---|---|
--comment |
-c |
Add an inline comment to the entry |
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.
remove ip¶
Remove an IP address and all hostnames associated with it.
remove cidr¶
Remove all addresses within one or more CIDR ranges.
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.
list ip¶
List hostnames associated with one or more IP addresses.
list cidr¶
List hostnames for all addresses within CIDR ranges.
list host¶
List IP addresses associated with one or more hostnames.
list bycomment¶
List all hosts that have a specific inline comment.
show¶
Display the full rendered hosts file.
version¶
Print the 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.
You can also set the TXEH_AUTO_FLUSH environment variable to always flush:
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.
| Platform | Command | Notes |
|---|---|---|
| macOS | dscacheutil -flushcache + killall -HUP mDNSResponder |
Ships with macOS. Works on 10.15 Catalina through current. |
| Linux | resolvectl flush-caches or systemd-resolve --flush-caches |
Requires systemd-resolved. See below. |
| Windows | ipconfig /flushdns |
Ships with all supported Windows versions. |
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.