1
0
mirror of https://github.com/octoleo/hosts.git synced 2024-10-31 18:52:31 +00:00
hosts/README.md
2017-12-31 09:02:09 -08:00

5.6 KiB

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

Hosts

A command line program for managing hosts file entries.

Installation

Homebrew

To install with Homebrew:

brew tap alphabetum/taps && brew install alphabetum/taps/hosts

bpkg

To install with bpkg:

bpkg install alphabetum/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/alphabetum/hosts/master/hosts \
  -o ~/bin/hosts && chmod +x ~/bin/hosts

Usage

Usage:
  hosts [<search string>]
  hosts add <ip> <hostname> [<comment>]
  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 block

Usage:
  hosts block <hostname>

Description:
  Block a given hostname by adding new entries assigning it 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 a given hostname by removing its entries from the hosts file.

hosts version

Usage:
  hosts (version | --version)

Description:
  Display the current program version.

Options

--auto-sudo

When specified, 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"

-h --help

Display help information.

--version

Display version information.

Tests

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

Acknowledgements