A cross-platform CLI tool that resolves hostnames against a specified DNS server and writes the resulting IP-to-hostname mappings into the local hosts file. It manages a clearly delimited block within the hosts file so it can cleanly add and remove only its own entries.

Built as a single static binary with no runtime dependencies.

Features

Resolve one or more hostnames via a specified DNS server and add them to the system hosts file
Remove individual hostnames or all managed entries from the hosts file
Managed block markers ensure only dns-helper's entries are modified — the rest of the hosts file is never touched
Automatic backup of the hosts file before every write (stored alongside the executable)
File-based lock prevents concurrent modifications
Cross-platform: Windows, macOS, and Linux

Requirements

Go 1.20 toolchain (this project must not use Go 1.21+ features)
Administrator / root privileges (required to modify the system hosts file)

Installation

Build from source

# Clone the repository
git clone <repo-url>
cd dns-helper

# Build for the current platform
.\build.ps1

# Or build optimized release binaries for all platforms
.\build.ps1 -Release -CrossCompile

The default build output is build\dns-helper.exe (Windows). Cross-compiled binaries are named build\dns-helper-<os>-<arch>[.exe].

Release packages

# Build release binaries and create distributable archives
.\build.ps1 -Release -CrossCompile -Package

Archives are written to releases\dns-helper-<version>-<os>-<arch>.zip (Windows) or .tar.gz (macOS/Linux).

Usage

Note: dns-helper must be run with elevated privileges (Run as Administrator on Windows, sudo on macOS/Linux) because it modifies the system hosts file.

Add entries

Resolve hostnames via a DNS server and add the resulting IP mappings to the hosts file:

dns-helper add -host hostname.example.com -server dns.example.com

Add multiple hostnames at once (comma-separated):

dns-helper add -host "host1.example.com,host2.example.com" -server dns.example.com

Short alias:

dns-helper a -host hostname.example.com -server dns.example.com

Delete entries

Remove a specific hostname:

dns-helper delete -host hostname.example.com

Remove multiple hostnames:

dns-helper delete -host "host1.example.com,host2.example.com"

Remove all managed entries:

dns-helper delete all

Short aliases: d, del

Command reference

Command	Flag	Required	Description
`add`	`-host`	Yes	Comma-separated hostnames to resolve and add
`add`	`-server`	Yes	DNS resolver to query (e.g. `dns.example.com`)
`delete`	`-host`	Yes (unless `all`)	Comma-separated hostnames to remove
`delete all`	—	—	Removes every entry dns-helper has written

Exit codes

Code	Meaning
0	Success
1	Error or partial failure (e.g. one hostname failed to resolve)

How it works

dns-helper wraps its entries between two marker lines in the hosts file:

# DNSHelper <<-> START CONFIG
192.0.2.1	hostname.example.com
# DNSHelper <->> END CONFIG

Only lines within this managed block are ever modified or removed. The rest of the hosts file is preserved exactly as-is.

Before every write, a backup of the hosts file is saved to the directory containing the dns-helper executable.

Hosts file locations

Platform	Path
Windows	`%SystemRoot%\System32\drivers\etc\hosts`
macOS	`/etc/hosts`
Linux	`/etc/hosts`

Project structure

main.go              CLI entry point (add / delete commands, flag parsing)
build.ps1            Build & packaging script
go.mod               Module definition (Go 1.20, golang.org/x/net)
hostfile/
  hostfile.go        Hosts file parsing, DNSEntry type, add/remove helpers
  managed.go         Managed block read/write logic
  filesystem.go      FileSystem interface + OSFileSystem implementation
  hostfile_test.go
  managed_test.go
lockfile/
  lockfile.go        File-based mutex to prevent concurrent modifications
  lockfile_test.go
platform/
  platform.go             Platform interface — GetHostsFilePath()
  platform_windows.go     Windows implementation
  platform_darwin.go      macOS implementation
  platform_linux.go       Linux implementation
  platform_test.go
resolver/
  resolver.go        DNS resolution via golang.org/x/net/dns/dnsmessage
  resolver_test.go

Development

Running tests

go1.20 test ./...

Running tests with coverage

go1.20 test -cover ./...

Vetting code

go1.20 vet ./...

Dependencies

golang.org/x/net — DNS message parsing (golang.org/x/net/dns/dnsmessage)

No other third-party dependencies. Standard library first.

README.md

dns-helper