hosts
__ __
/ /_ ____ _____/ /______
/ __ \/ __ \/ ___/ __/ ___/
/ / / / /_/ (__ ) /_(__ )
/_/ /_/\____/____/\__/____/
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
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.
Copyright (c) 2015-present William Melody • See LICENSE for details.