hosts.sh.xibai

    3.6.4 • Public • Published

    Build Status

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

    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)addbackupsblockcompletionsdisabledisablededitenableenabledfilehelplistremovesearchshowsubcommandsunblockversion

    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.

    github.com/xwmx/hosts

    Install

    npm i hosts.sh.xibai

    DownloadsWeekly Downloads

    4

    Version

    3.6.4

    License

    MIT

    Unpacked Size

    138 kB

    Total Files

    30

    Last publish

    Collaborators

    • sike.xibai