Go to file
William Melody b8c4ec06b9 Add .travis.yml 2020-04-12 15:34:56 -07:00
test Just use `diff` in `backups compare`. 2020-04-08 21:25:01 -07:00
.shellcheckrc Update documentation in .shellcheckrc. 2020-03-15 11:40:13 -07:00
.travis.yml Add .travis.yml 2020-04-12 15:34:56 -07:00
LICENSE Add license 2015-03-18 18:39:22 -07:00
Makefile Add basic Makefile 2015-05-20 16:46:02 -07:00
README.md Modify example in README.md 2020-04-08 21:36:52 -07:00
hosts Update version to 3.3.1 2020-04-08 21:42:38 -07:00
hosts.autocomplete.bash Add autocomplete functions for bash and zsh. 2017-03-01 12:30:25 -08:00
hosts.autocomplete.zsh Add autocomplete functions for bash and zsh. 2017-03-01 12:30:25 -08:00
package-lock.json Update version to 3.3.1 2020-04-08 21:42:38 -07:00
package.json Update version to 3.3.1 2020-04-08 21:42:38 -07:00

README.md

    __               __
   / /_  ____  _____/ /______
  / __ \/ __ \/ ___/ __/ ___/
 / / / / /_/ (__  ) /_(__  )
/_/ /_/\____/____/\__/____/

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 install xwmx/taps/hosts

npm

To install with npm:

npm install --global hosts.sh

bpkg

To install with bpkg:

bpkg install xwmx/hosts

Manual

To install manually, simply add the hosts script to your $PATH. If you already have a ~/bin directory, you can use the following command:

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

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

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 records:
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

Add 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 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 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>

Commands

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 records 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.

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.

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.

Blocklists

hosts commands

Usage:
  hosts commands [--raw]

Options:
  --raw  Display the command list without formatting.

Description:
  Display the list of available commands.

hosts disable

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

Description:
  Disable one or more records based on a given ip address, hostname, or
  search string.

hosts disabled

Usage:
  hosts disabled

Description:
  List all disabled records. This is an alias for `hosts list disabled`.

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 records based on a given ip address, hostname,
  or search string.

hosts enabled

Usage:
  hosts enabled

Description:
  List all enabled records. This is an alias for `hosts list enabled`.

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 records will
  be printed.

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 records based on a given IP address, hostname, or search
  string. If an IP and hostname are both provided, only records matching the
  IP and hostname pair will be removed.
Usage:
  hosts search <search string>

Description:
  Search entries for <search string>.

hosts show

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

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

hosts unblock

Usage:
  hosts unblock <hostname>...

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

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.

Acknowledgements