CLI reference

Global options

These work on every subcommand.

Option	Description
`-c, --config <FILE>`	Path to the config (default: ~/.config/hostsctl/config.yaml)
`--target <FILE>`	File to manage (default: /etc/hosts)
`-n, --dry-run`	Write nothing, only show what would happen

Commands at a glance

Command	What it does
`hostsctl apply`	Render the config into /etc/hosts (needs root)
`hostsctl diff`	Show the diff between the current /etc/hosts and what apply would write
`hostsctl status`	Report on the config, the managed block, groups and backups
`hostsctl off`	Remove the managed block from /etc/hosts, leaving the config alone (needs root)
`hostsctl list`	List the entries in the config
`hostsctl search`	Find entries by a substring of a hostname or an IP
`hostsctl add`	Add an entry
`hostsctl rm`	Remove entries by hostname or IP
`hostsctl enable`	Enable entries by hostname
`hostsctl disable`	Disable entries by hostname (they stay in the config)
`hostsctl group`	Groups of entries
`hostsctl zone`	Zone files next to the config
`hostsctl source`	Remote blocklists
`hostsctl backup`	Backups of /etc/hosts
`hostsctl import`	Import existing *.hosts files into the config
`hostsctl migrate`	Move a legacy hosts-sync setup into the config and drop its block
`hostsctl check`	Check the config for things /etc/hosts would silently ignore
`hostsctl edit`	Open the config (or a group’s file) in $EDITOR and check it afterwards
`hostsctl init`	Create a config from scratch
`hostsctl config-path`	Print the path to the config and to every attached zone
`hostsctl completions`	Print a shell completion script
`hostsctl man`	Print the man page in roff format

`hostsctl apply`

Render the config into /etc/hosts (needs root)

hostsctl apply [OPTIONS]

Option	Description
`-y, --yes`	Do not ask for confirmation
`--no-flush`	Do not flush the DNS cache
`--drop-legacy`	Also drop the block left behind by the legacy hosts-sync

`hostsctl diff`

Show the diff between the current /etc/hosts and what apply would write

hostsctl diff [OPTIONS]

`hostsctl status`

Report on the config, the managed block, groups and backups

hostsctl status [OPTIONS]

`hostsctl off`

Remove the managed block from /etc/hosts, leaving the config alone (needs root)

hostsctl off [OPTIONS]

Option	Description
`-y, --yes`	Do not ask for confirmation

`hostsctl list`

List the entries in the config

hostsctl list [OPTIONS]

Option	Description
`-g, --group <GROUP>`	Only this group
`-a, --all`	Show disabled entries too

`hostsctl search`

Find entries by a substring of a hostname or an IP

hostsctl search <PATTERN> [OPTIONS]

Option	Description
`<PATTERN>`	Substring to look for in hostnames, addresses and comments

`hostsctl add`

Add an entry

hostsctl add <IP> <HOSTNAMES>... [OPTIONS]

Option	Description
`<IP>`	Address the hostnames resolve to
`<HOSTNAMES>...`	One or more hostnames
`-g, --group <GROUP>`	Group (created when it does not exist) (default: `local`)
`--file <FILE>`	Zone file for a new group (for example zones/work.yaml)
`--comment <COMMENT>`	Comment kept next to the entry
`--disabled`	Add it disabled
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl rm`

Remove entries by hostname or IP

Alias: remove

hostsctl rm <TARGETS>... [OPTIONS]

Option	Description
`<TARGETS>...`	Hostnames or IPs
`-g, --group <GROUP>`	Look only in this group
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl enable`

Enable entries by hostname

hostsctl enable <HOSTNAMES>... [OPTIONS]

Option	Description
`<HOSTNAMES>...`	One or more hostnames
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl disable`

Disable entries by hostname (they stay in the config)

hostsctl disable <HOSTNAMES>... [OPTIONS]

Option	Description
`<HOSTNAMES>...`	One or more hostnames
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl group`

Groups of entries

hostsctl group <COMMAND> [OPTIONS]

`hostsctl group list`

List the groups

hostsctl group list [OPTIONS]

`hostsctl group add`

Create a group

hostsctl group add <NAME> [OPTIONS]

Option	Description
`<NAME>`	Group name
`-d, --description <DESCRIPTION>`	Human-readable description, rendered as a comment in /etc/hosts
`--file <FILE>`	Put the group in a zone file (for example zones/work.hosts)
`--disabled`	Create it disabled

`hostsctl group move`

Move a group to another file (‘main’ means the main config)

hostsctl group move <NAME> [OPTIONS]

Option	Description
`<NAME>`	Group name
`--file <FILE>`	Destination zone file, or ‘main’ for the main config

`hostsctl group rm`

Delete a group together with its entries

hostsctl group rm <NAME> [OPTIONS]

Option	Description
`<NAME>`	Group name
`-y, --yes`	Do not ask for confirmation

`hostsctl group enable`

Enable a group

hostsctl group enable <NAME> [OPTIONS]

Option	Description
`<NAME>`	Group name
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl group disable`

Disable a group

hostsctl group disable <NAME> [OPTIONS]

Option	Description
`<NAME>`	Group name
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl zone`

Zone files next to the config

hostsctl zone <COMMAND> [OPTIONS]

`hostsctl zone list`

Show the include patterns and the files they match

hostsctl zone list [OPTIONS]

`hostsctl zone add`

Attach a file or a pattern (for example ‘zones/*.hosts’)

hostsctl zone add <PATTERN> [OPTIONS]

Option	Description
`<PATTERN>`	Path or glob, relative to the config directory

`hostsctl zone rm`

Detach a pattern; the files stay on disk

hostsctl zone rm <PATTERN> [OPTIONS]

Option	Description
`<PATTERN>`	Pattern exactly as it appears in include

`hostsctl source`

Remote blocklists

hostsctl source <COMMAND> [OPTIONS]

`hostsctl source list`

List the remote sources and the state of their cache

hostsctl source list [OPTIONS]

`hostsctl source add`

Attach a remote hosts list as a group

hostsctl source add <URL> [OPTIONS]

Option	Description
`<URL>`	http(s) address of the hosts list
`-g, --group <GROUP>`	Group name
`--rewrite-ip <REWRITE_IP>`	Rewrite the IP of every entry (usually 0.0.0.0)
`--allow <ALLOW>`	Hostnames to keep out of the list
`--file <FILE>`	Zone file for the group (.yaml only)
`--update`	Download it right away

`hostsctl source rm`

Detach a source (drops the group and its cache)

hostsctl source rm <GROUP> [OPTIONS]

Option	Description
`<GROUP>`	Group the source belongs to
`-y, --yes`	Do not ask for confirmation

`hostsctl source update`

Download the lists again

hostsctl source update [GROUP] [OPTIONS]

Option	Description
`<GROUP>`	A single group; all of them when omitted
`--force`	Ignore the cached ETag
`--apply`	Apply to /etc/hosts right away (needs root)

`hostsctl backup`

Backups of /etc/hosts

hostsctl backup <COMMAND> [OPTIONS]

`hostsctl backup list`

List the snapshots

hostsctl backup list [OPTIONS]

`hostsctl backup restore`

Roll /etc/hosts back to a snapshot (needs root)

hostsctl backup restore [ID] [OPTIONS]

Option	Description
`<ID>`	Snapshot ID; the latest one when omitted
`-y, --yes`	Do not ask for confirmation

`hostsctl backup prune`

Delete snapshots beyond settings.keep_backups

hostsctl backup prune [OPTIONS]

`hostsctl import`

Import existing *.hosts files into the config

hostsctl import <PATHS>... [OPTIONS]

Option	Description
`<PATHS>...`	*.hosts files, or directories holding them
`-g, --group <GROUP>`	Put everything in one group instead of a group per file

`hostsctl migrate`

Move a legacy hosts-sync setup into the config and drop its block

hostsctl migrate [OPTIONS]

Option	Description
`--from <DIR>`	Directory holding the *.hosts files of the legacy hosts-sync (default: `.`)
`-y, --yes`	Do not ask for confirmation

`hostsctl check`

Check the config for things /etc/hosts would silently ignore

hostsctl check [OPTIONS]

`hostsctl edit`

Open the config (or a group’s file) in $EDITOR and check it afterwards

hostsctl edit [GROUP] [OPTIONS]

Option	Description
`<GROUP>`	Open the file this group lives in

`hostsctl init`

Create a config from scratch

hostsctl init [OPTIONS]

Option	Description
`--force`	Overwrite an existing config
`--from <DIR>`	Import the *.hosts files in this directory into the new config

`hostsctl config-path`

Print the path to the config and to every attached zone

hostsctl config-path [OPTIONS]

Option	Description
`-a, --all`	Print the zone files as well

`hostsctl completions`

Print a shell completion script

hostsctl completions <SHELL> [OPTIONS]

Option	Description
`<SHELL>`	Shell to generate the script for

`hostsctl man`

Print the man page in roff format

hostsctl man [OPTIONS]

The same information elsewhere

hostsctl --help prints the command list, hostsctl <command> --help narrows it to one command, and hostsctl man writes a man page in roff format:

hostsctl man > /usr/local/share/man/man1/hostsctl.1

Two commands are deliberately absent from the list above. hostsctl docs cli and hostsctl docs exit-codes print the raw markdown this page is assembled from; they exist for make gen and are hidden from --help.

Which of these need root

Writing to /etc/hosts or to the backup directory needs root, and nothing else does — see Permissions and sudo for the full split and for what happens to file ownership under sudo.