    __               __

   / /_  ____  _____/ /______

  / __ \/ __ \/ ___/ __/ ___/

 / / / / /_/ (__  ) /_(__  )

/_/ /_/\____/____/\__/____/

Hosts

hosts is a command line program for managing hosts file entries.

hosts works with existing hosts files and entries, making it easier to add, remove, comment, and search hosts file entries using simple, memorable commands.

hosts is designed to be lightweight, easy to use, and contained in a single, portable script that can be curled into any environment.

Installation

Homebrew

To install with Homebrew:

brew tap xwmx/taps

brew install hosts

npm

To install with npm:

npm install --global hosts.sh

bpkg

To install with bpkg:

bpkg install xwmx/hosts

Make

To install with Make, clone this repository, navigate to the clone's root directory, and run:

sudo make install

Manual

To install as an administrator, copy and paste one of the following multi-line commands:

# install using wget

sudo wget https://raw.github.com/xwmx/hosts/master/hosts -O /usr/local/bin/hosts &&

  sudo chmod +x /usr/local/bin/hosts &&

  sudo hosts completions install



# install using curl

sudo curl -L https://raw.github.com/xwmx/hosts/master/hosts -o /usr/local/bin/hosts &&

  sudo chmod +x /usr/local/bin/hosts &&

  sudo hosts completions install

User-only Installation

To install with just user permissions, simply add the hosts script to your $PATH. If you already have a ~/bin directory, for example, you can use one of the following commands:

# download with wget

wget https://raw.github.com/xwmx/hosts/master/hosts -O ~/bin/hosts && chmod +x ~/bin/hosts



# download with curl

curl -L https://raw.github.com/xwmx/hosts/master/hosts -o ~/bin/hosts && chmod +x ~/bin/hosts

Installing with just user permissions doesn't install the completions, but hosts works without them. If you have sudo access and want to install the completion scripts, run the following command:

sudo hosts completions install

Arch Linux

A package for Arch users is also available in the AUR.

Tab Completion

Bash and Zsh tab completion is enabled when hosts is installed using Homebrew, npm, bpkg, or Make. If you are installing hosts manually, completion can be enabled with a few commands.

Usage

Listing Entries

hosts with no arguments lists the entries in the system's hosts file:

> hosts

127.0.0.1       localhost

255.255.255.255 broadcasthost

::1             localhost

fe80::1%lo0     localhost

hosts called with a string or regular expression will search for entries that match.

> hosts localhost

127.0.0.1   localhost

::1         localhost

fe80::1%lo0 localhost



> hosts '\d\d\d'

127.0.0.1         localhost

255.255.255.255   broadcasthost

Adding Entries

To add an entry, use hosts add:

> hosts add 127.0.0.1 example.com

Added:

127.0.0.1 example.com

Run hosts or hosts list to see the new entry in the list:

> hosts

127.0.0.1         localhost

255.255.255.255   broadcasthost

::1               localhost

fe80::1%lo0       localhost

127.0.0.1         example.com

Removing Entries

To remove an entry, use hosts remove, which can take an IP address, domain, or regular expression:

> hosts remove example.com

Removing the following entries:

127.0.0.1	example.com

Are you sure you want to proceed? [y/N] y

Removed:

127.0.0.1	example.com

Blocking and Unblocking Domains

hosts provides easy commands for blocking and unblocking domains with IPv4 and IPv6 entries:

> hosts block example.com

Added:

127.0.0.1   example.com

Added:

fe80::1%lo0 example.com

Added:

::1         example.com



> hosts unblock example.com

Removed:

127.0.0.1   example.com

Removed:

fe80::1%lo0 example.com

Removed:

::1         example.com

Enabling / Disabling Entries

All entries are enabled by default. Disabiling an entry comments it out so it has no effect, but remains in the hosts file ready to be enabled again.

> hosts

127.0.0.1         localhost

255.255.255.255   broadcasthost

::1               localhost

fe80::1%lo0       localhost

127.0.0.1         example.com



> hosts disable example.com

Disabling:

127.0.0.1	example.com



> hosts

127.0.0.1         localhost

255.255.255.255   broadcasthost

::1               localhost

fe80::1%lo0       localhost



Disabled:

---------

127.0.0.1         example.com



> hosts enable example.com

Enabling:

127.0.0.1	example.com



> hosts

127.0.0.1         localhost

255.255.255.255   broadcasthost

::1               localhost

fe80::1%lo0       localhost

127.0.0.1         example.com

Backups

Create backups of your hosts file with hosts backups create:

> hosts backups create

Backed up to /etc/hosts--backup-20200101000000

List your backups with hosts backups. If you have existing hosts file backups, hosts will include them:

> hosts backups

hosts--backup-20200101000000

hosts.bak

hosts backups compare will open your hosts file with diff:

> hosts backups compare hosts--backup-20200101000000

--- /etc/hosts	2020-01-01 00:00:00.000000000

+++ /etc/hosts--backup-20200101000000	2020-01-01 00:00:00.000000000

@@ -8,3 +8,4 @@

 255.255.255.255  broadcasthost

 ::1              localhost

 fe80::1%lo0      localhost

+127.0.0.1        example.com

View a backup with hosts backups show:

> hosts backups show hosts--backup-20200101000000

##

# Host Database

#

# localhost is used to configure the loopback interface

# when the system is booting.  Do not change this entry.

##

127.0.0.1       localhost

255.255.255.255 broadcasthost

::1             localhost

fe80::1%lo0     localhost

127.0.0.1       example.com

Restore a backup with hosts backups restore. Before a backup is restored, a new one is created to avoid data loss:

> hosts backups restore hosts--backup-20200101000000

Backed up to /etc/hosts--backup-20200102000001

Restored from backup: hosts--backup-20200101000000

Viewing and Editing `/etc/hosts` Directly

hosts file prints the raw contents of /etc/hosts:

> hosts file

##

# Host Database

#

# localhost is used to configure the loopback interface

# when the system is booting.  Do not change this entry.

##

127.0.0.1       localhost

255.255.255.255 broadcasthost

::1             localhost

fe80::1%lo0     localhost

hosts edit opens /etc/hosts in your editor:

> hosts edit

`--auto-sudo`

When the --auto-sudo flag is used, all write operations that require sudo will automatically rerun the command using sudo when the current user does not have write permissions for the hosts file.

To have this option always enabled, add the following line to your shell configuration (.bashrc, .zshrc, or similar):

alias hosts="hosts --auto-sudo"

Help

Usage:

  hosts [<search string>]

  hosts add <ip> <hostname> [<comment>]

  hosts backups [create | (compare | delete | restore | show) <filename>]

  hosts block <hostname>...

  hosts completions (check | install [-d | --download] | uninstall)

  hosts disable (<ip> | <hostname> | <search string>)

  hosts disabled

  hosts edit

  hosts enable (<ip> | <hostname> | <search string>)

  hosts enabled

  hosts file

  hosts list [enabled | disabled | <search string>]

  hosts search <search string>

  hosts show (<ip> | <hostname> | <search string>)

  hosts subcommands [--raw]

  hosts remove (<ip> | <hostname> | <search string>) [--force]

  hosts unblock <hostname>...

  hosts --auto-sudo

  hosts -h | --help

  hosts --version



Options:

  --auto-sudo  Run write commands with `sudo` automatically.

  -h --help    Display this help information.

  --version    Display version information.



Help:

  hosts help [<command>]

For full usage, run:

hosts help

For help with a particular command, try:

hosts help <command name>

Subcommands

(default) • add • backups • block • completions • disable • disabled • edit • enable • enabled • file • help • list • remove • search • show • subcommands • unblock • version

`hosts`

Usage:

  hosts [<search string>]



Description:

  List the existing IP / hostname pairs, optionally limited to a specified

  state. When provided with a seach string, all matching enabled entries will

  be printed.



  Alias for `hosts list`

`hosts add`

Usage:

  hosts add <ip> <hostname> [<comment>]



Description:

  Add a given IP address and hostname pair, along with an optional comment.



Exit status:

  0   Entry successfully added.

  1   Invalid parameters or entry exists.

`hosts backups`

Usage:

  hosts backups

  hosts backups create

  hosts backups compare <filename>

  hosts backups delete  <filename>

  hosts backups restore <filename> [--skip-backup]

  hosts backups show    <filename>



Subcommands:

  backups           List available backups.

  backups create    Create a new backup of the hosts file.

  backups compare   Compare a backup file with the current hosts file.

  backups delete    Delete the specified backup.

  backups restore   Replace the contents of the hosts file with a

                    specified backup. The hosts file is automatically

                    backed up before being overwritten unless the

                    '--skip-backup' flag is specified.

  backups show      Show the contents of the specified backup file.



Description:

  Manage backups.



Exit status:

  0   Success.

  1   Invalid parameters or backup not found.

`hosts block`

Usage:

  hosts block <hostname>...



Description:

  Block one or more hostnames by adding new entries assigned to `127.0.0.1`

  for IPv4 and both `fe80::1%lo0` and `::1` for IPv6.



Exit status:

  0   <hostname> successfully blocked.

  1   Invalid parameters or entry exists.

Blocklists

jmdugan/blocklists

notracking/hosts-blocklists

`hosts completions`

Usage:

  hosts completions (check | install [-d | --download] | uninstall)



Options:

  -d, --download  Download the completion scripts and install.



Description:

  Manage completion scripts. For more information, visit:

  https://github.com/xwmx/hosts/blob/master/etc/README.md



Exit status:

  0   Completions successfully installed.

  1   Invalid parameters or other error.

`hosts disable`

Usage:

  hosts disable (<ip> | <hostname> | <search string>)



Description:

  Disable one or more entries based on a given ip address, hostname, or

  search string.



Exit status:

  0   Entry successfully disabled.

  1   Invalid parameters or entry not found.

`hosts disabled`

Usage:

  hosts disabled



Description:

  List all disabled entries. This is an alias for `hosts list disabled`.



Exit status:

  0   One or more disabled entries found.

  1   Invalid parameters or no disabled entries found.

`hosts edit`

Usage:

  hosts edit



Description:

  Open the /etc/hosts file in your $EDITOR.

`hosts enable`

Usage:

  hosts enable (<ip> | <hostname> | <search string>)



Description:

  Enable one or more disabled entries based on a given ip address, hostname,

  or search string.



Exit status:

  0   Entry successfully enabled.

  1   Invalid parameters or entry not found.

`hosts enabled`

Usage:

  hosts enabled



Description:

  List all enabled entries. This is an alias for `hosts list enabled`.



Exit status:

  0   One or more enabled entries found.

  1   Invalid parameters or no enabled entries found.

`hosts file`

Usage:

  hosts file



Description:

  Print the entire contents of the /etc/hosts file.

`hosts help`

Usage:

  hosts help [<command>]



Description:

  Display help information for hosts or a specified command.

`hosts list`

Usage:

  hosts list [enabled | disabled | <search string>]



Description:

  List the existing IP / hostname pairs, optionally limited to a specified

  state. When provided with a seach string, all matching enabled entries will

  be printed.



Exit status:

  0   One or more matching entries found.

  1   Invalid parameters or entry not found.

`hosts remove`

Usage:

  hosts remove (<ip> | <hostname> | <search string>) [--force]

  hosts remove <ip> <hostname>



Options:

  --force  Skip the confirmation prompt.



Description:

  Remove one or more entries based on a given IP address, hostname, or search

  string. If an IP and hostname are both provided, only entries matching the

  IP and hostname pair will be removed.



Exit status:

  0   Entry successfully removed.

  1   Invalid parameters or entry not found.

`hosts search`

Usage:

  hosts search <search string>



Description:

  Search entries for <search string>.



Exit status:

  0   One or more matching entries found.

  1   Invalid parameters or entry not found.

`hosts show`

Usage:

  hosts show (<ip> | <hostname> | <search string>)



Description:

  Print entries matching a given IP address, hostname, or search string.



Exit status:

  0   One or more matching entries found.

  1   Invalid parameters or entry not found.

`hosts subcommands`

Usage:

  hosts subcommands [--raw]



Options:

  --raw  Display the subcommands list without formatting.



Description:

  Display the list of available subcommands.

`hosts unblock`

Usage:

  hosts unblock <hostname>...



Description:

  Unblock one or more hostnames by removing the entries from the hosts file.



Exit status:

  0   <hostname> successfully unblocked.

  1   Invalid parameters or entry not found

`hosts version`

Usage:

  hosts (version | --version)



Description:

  Display the current program version.

Tests

To run the test suite, install Bats and run bats test in the project root directory.

github.com/xwmx/hosts

hosts

Hosts

Installation

Homebrew

npm

bpkg

Make

Manual

User-only Installation

Arch Linux

Tab Completion

Usage

Listing Entries

Adding Entries

Removing Entries

Blocking and Unblocking Domains

Enabling / Disabling Entries

Backups

Viewing and Editing /etc/hosts Directly

--auto-sudo

Help

Subcommands

hosts

hosts add

hosts backups

hosts block

Blocklists

hosts completions

hosts disable

hosts disabled

hosts edit

hosts enable

hosts enabled

hosts file

hosts help

hosts list

hosts remove

hosts search

hosts show

hosts subcommands

hosts unblock

hosts version