Skip to content
hostsctl
hostsctl — manage /etc/hosts from a YAML config: groups, zone files, remote blocklists, backups

hostsctl

One YAML config. Everything else in /etc/hosts stays exactly where you left it.
Getting startedInstallView on GitHub

Thirty seconds

Section titled “Thirty seconds”

  1. Install it and create a config:

    Terminal window
    brew install jtprogru/tap/hostsctl
    hostsctl init

  2. Add an entry — it goes into the config, not into /etc/hosts yet:

    Terminal window
    hostsctl add 127.0.0.1 k8s.orb.local --comment orbstack

  3. Look before you write. diff needs no root and changes nothing:

    Terminal window
    hostsctl diff

  4. Apply it:

    Terminal window
    sudo hostsctl apply

The result in /etc/hosts:

127.0.0.1  localhost          ← system lines, untouched
255.255.255.255  broadcasthost


# >>> hostsctl begin >>>
# generated by hostsctl 2026-08-11 17:15
# source: /Users/you/.config/hostsctl/config.yaml — edit that, not this block


# --- local — Local development ---
127.0.0.1      k8s.orb.local  # orbstack
# <<< hostsctl end <<<

Why it works this way

Section titled “Why it works this way”

Your file stays your file

Entries are rendered into a block between markers. System lines, other tools’ blocks and hand edits are carried over byte for byte — verified by tests that run against a copy of a real /etc/hosts.

Groups you can switch off

A group is enabled or disabled as a whole. Turn a blocklist off for an afternoon, turn it back on, and nothing in the config was lost in between.

Config split across files

Keep everything in one config.yaml, or spread it over zone files — plain hosts syntax or YAML. Edits made through the CLI go back to the file the group came from.

Honest about failure

Atomic writes with fsync and rename, a snapshot before every write, a refusal to produce a file without 127.0.0.1 localhost, and an exit code for every way a run can go wrong.

Where to go next

Section titled “Where to go next”

New here? Read the two pages under Start here, then come back for whichever guide matches what you are trying to do.

Getting startedFrom an empty config to a rendered /etc/hosts in five commands, and the three ways to undo it.
InstallationHomebrew, crates.io, the install script, a release archive, and how to verify a download.

Guides — one task each

Section titled “Guides — one task each”
ConfigurationWhat lives in config.yaml, how entries map addresses to names, where the file is looked up.
GroupsSets of entries that switch on and off as a whole, and how to move them between files.
Zone filesSplitting the config across files, in YAML or in plain hosts syntax.
Remote blocklistsAttaching a hosts list by URL, the ETag cache, and why apply never touches the network.
BackupsA snapshot before every write, how to roll one back, and what a snapshot is not.
Permissions and sudoWhich commands need root, and why sudo leaves no root-owned files in your home directory.

Reference — generated from the code

Section titled “Reference — generated from the code”
CLI referenceEvery command and flag, printed by the binary itself. CI fails if it drifts.
Config referenceEvery key of config.yaml and of a zone file, with its default and its meaning.
Validation rulesEverything hostsctl check reports, and whether it stops a write.
Exit codesWhat each status means, so a script can tell a broken config from a missing sudo.

Project

Section titled “Project”
How it worksThe managed block, the six steps of a write, and why the timestamp does not change on its own.
Migrating from hosts-syncTwo ways across from the older shell script, and what happens to its block.
ContributingHow to build, test and propose a change — including the docs site.

What it is not

Section titled “What it is not”

hostsctl does not resolve names — /etc/hosts does, with all of its limits. Wildcards, ports and paths in a hostname do not work there, so hostsctl check rejects them instead of letting the system ignore them silently. For wildcard domains you want dnsmasq or /etc/resolver/.