repository·master·Indexed 21 days ago
https://github.com/cbednarski/hostessAn idempotent command-line utility for managing system hosts files (/etc/hosts on Unix/Linux/macOS and C:\Windows\System32\drivers\etc\hosts on Windows). It provides a CLI and Go API to add, remove, enable, disable, and list hostnames, as well as tools to format the hosts file and export/import configurations via JSON.
hostess adapts its writing style based on the operating system or the HOSTESS_FMT variable:
Follows the standard man hosts format where multiple hostnames can share a single line per IP address:
127.0.0.1 localhost hostname2 hostname3
127.0.1.1 machine.name
# 10.10.20.30 some.hostWrites each hostname on its own individual line:
127.0.0.1 localhost
127.0.0.1 hostname2
127.0.0.1 hostname3hostess is an idempotent command-line utility for managing your /etc/hosts (Unix) or C:\Windows\System32\drivers\etc\hosts (Windows) file.
Permissions Note: Because the hosts file is a protected system file, you must run hostess with elevated privileges:
sudo or run as root.Common commands include adding entries for specific hostnames and IP addresses.
hostess add local.example.com 127.0.0.1
hostess add staging.example.com 10.0.2.16You can install hostess by downloading a precompiled release from GitHub or by building it from source using Go. To build from source, clone the repository and use make install.
git clone https://github.com/cbednarski/hostess
cd hostess
make installYou can override the default platform detection and file locations using the following environment variables:
HOSTESS_FMT: Set to windows or unix to force a specific hosts file format.unix format: One line per IP address (e.g., 127.0.0.1 host1 host2).windows format: Each hostname on its own line (e.g., 127.0.0.1 host1\n127.0.0.1 host2).HOSTESS_PATH: Set this to override the default location of the hosts file./etc/hostsC:\Windows\System32\drivers\etc\hostsThe commands.go file provides a high-level API for managing a system's hosts file. It wraps the core hostess library to provide common operations like adding, removing, enabling, disabling, and listing hostnames. Most functions accept an *Options struct which can control whether changes are actually written to disk or just previewed via stdout.
// Example: Adding a host
err := Add(&Options{Preview: false}, "example.com", "127.0.0.1")
// Example: Checking if a host exists
err := Has(&Options{Preview: false}, "example.com")The Options struct is used to control the behavior of the command functions, specifically regarding how changes are persisted.
| Field | Type | Description |
|---|---|---|
Preview | bool | If true, the command will not write changes to the hosts file. Instead, it will output the resulting formatted hosts file to stdout. This is useful for dry-runs. |
type Options struct {
Preview bool
}These functions toggle the active status of a hostname in the hosts file (typically by commenting or uncommenting the line).
Activates a hostname.
err := Enable(options, "hostname.com")Deactivates a hostname.
err := Disable(options, "hostname.com")Disable will print an error to stderr but will not return an error, as the desired state (the host being disabled/absent) is already achieved.// Enable a host
err := Enable(options, "example.com")
// Disable a host
err := Disable(options, "example.com")The Remove function deletes any hostname matching the provided domain from the hosts file.
Parameters:
options *Options: Configuration.hostname string: The domain name to remove.Returns:
error: Returns an error if loading the hostfile fails or if saving/previewing fails.err := Remove(options, "oldhost.local")The Add function parses a hostname and an IP address, then adds or updates that entry in the hosts file. If the domain already exists, the entry is updated. The operation is idempotent.
Parameters:
options *Options: Configuration (use Preview: true for a dry-run).hostname string: The domain name to add.ip string: The IP address to associate with the domain.Returns:
error: Returns an error if the hostname creation fails or if saving/previewing fails.err := Add(options, "myhost.local", "10.0.0.1")The Has function checks if a specific hostname is present in the hosts file.
Behavior:
nil.os.Exit(1). This makes it suitable for use in shell scripts to verify presence.Parameters:
options *Options: Configuration.hostname string: The domain name to check.Returns:
error: Returns an error if loading the hostfile fails.// In a script, this will exit with 1 if not found
err := Has(options, "exists.com")The Format function cleans up the hosts file by removing duplicate entries and resolving conflicts. If the file is already formatted and contains no duplicates, the function performs no action.
Parameters:
options *Options: Configuration.Returns:
error: Returns an error if loading or saving fails.err := Format(options)The Apply function reads a JSON file containing host configurations and applies them to the current hosts file.
Parameters:
options *Options: Configuration.filename string: The path to the JSON file containing the host data.Returns:
error: Returns an error if the file cannot be read, if the JSON is invalid, or if applying the changes fails.err := Apply(options, "hosts_backup.json")