{"id":13496019,"url":"https://github.com/xwmx/hosts","last_synced_at":"2025-05-08T18:48:32.696Z","repository":{"id":28836676,"uuid":"32360343","full_name":"xwmx/hosts","owner":"xwmx","description":"A command line hosts file editor in one portable script.","archived":false,"fork":false,"pushed_at":"2023-06-27T23:59:18.000Z","size":486,"stargazers_count":164,"open_issues_count":7,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-29T01:06:17.614Z","etag":null,"topics":["bash","blocklists","cli","command-line","hostname","hosts","linux","macos","networking","shell","unix"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xwmx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["xwmx"],"custom":"https://paypal.me/WilliamMelody"}},"created_at":"2015-03-16T23:58:45.000Z","updated_at":"2024-11-10T06:59:15.000Z","dependencies_parsed_at":"2024-01-16T09:54:10.905Z","dependency_job_id":"d830eafa-11da-47ee-9427-5bda482a0a90","html_url":"https://github.com/xwmx/hosts","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fhosts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fhosts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fhosts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fhosts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xwmx","download_url":"https://codeload.github.com/xwmx/hosts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253133116,"owners_count":21859108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","blocklists","cli","command-line","hostname","hosts","linux","macos","networking","shell","unix"],"created_at":"2024-07-31T19:01:40.791Z","updated_at":"2025-05-08T18:48:32.676Z","avatar_url":"https://github.com/xwmx.png","language":"Shell","readme":"[![Build Status](https://img.shields.io/github/actions/workflow/status/xwmx/hosts/tests.yml?branch=master)](https://github.com/xwmx/hosts/actions)\n\n        __               __\n       / /_  ____  _____/ /______\n      / __ \\/ __ \\/ ___/ __/ ___/\n     / / / / /_/ (__  ) /_(__  )\n    /_/ /_/\\____/____/\\__/____/\n\n# Hosts\n\n`hosts` is a command line program for managing\n[hosts file](https://en.wikipedia.org/wiki/Hosts_\\(file\\)) entries.\n\n`hosts` works with existing hosts files and entries, making it easier to add,\nremove, comment, and search hosts file entries using simple, memorable\ncommands.\n\n`hosts` is designed to be lightweight, easy to use, and contained in a\nsingle, portable script that can be `curl`ed into any environment.\n\n## Installation\n\n### Homebrew\n\nTo install with [Homebrew](http://brew.sh/):\n\n```bash\nbrew tap xwmx/taps\nbrew install hosts\n```\n\n### npm\n\nTo install with [npm](https://www.npmjs.com/package/hosts.sh):\n\n```bash\nnpm install --global hosts.sh\n```\n\n### bpkg\n\nTo install with [bpkg](https://github.com/bpkg/bpkg):\n\n```bash\nbpkg install xwmx/hosts\n```\n\n### Make\n\nTo install with [Make](https://en.wikipedia.org/wiki/Make_(software)),\nclone this repository, navigate to the clone's root directory, and run:\n\n```bash\nsudo make install\n```\n\n### Manual\n\nTo install as an administrator, copy and paste one of the following multi-line\ncommands:\n\n```bash\n# install using wget\nsudo wget https://raw.github.com/xwmx/hosts/master/hosts -O /usr/local/bin/hosts \u0026\u0026\n  sudo chmod +x /usr/local/bin/hosts \u0026\u0026\n  sudo hosts completions install\n\n# install using curl\nsudo curl -L https://raw.github.com/xwmx/hosts/master/hosts -o /usr/local/bin/hosts \u0026\u0026\n  sudo chmod +x /usr/local/bin/hosts \u0026\u0026\n  sudo hosts completions install\n```\n\n###### User-only Installation\n\nTo install with just user permissions, simply add the `hosts` script to your\n`$PATH`. If you already have a `~/bin` directory, for example, you can use\none of the following commands:\n\n```bash\n# download with wget\nwget https://raw.github.com/xwmx/hosts/master/hosts -O ~/bin/hosts \u0026\u0026 chmod +x ~/bin/hosts\n\n# download with curl\ncurl -L https://raw.github.com/xwmx/hosts/master/hosts -o ~/bin/hosts \u0026\u0026 chmod +x ~/bin/hosts\n```\n\nInstalling with just user permissions doesn't install the completions, but\n`hosts` works without them. If you have `sudo` access and want to install the\ncompletion scripts, run the following command:\n\n```bash\nsudo hosts completions install\n```\n\n### Arch Linux\n\nA package for Arch users is also\n[available in the AUR](https://aur.archlinux.org/packages/hosts/).\n\n### Tab Completion\n\nBash and Zsh tab completion is enabled when `hosts` is installed using\nHomebrew, npm, bpkg, or Make. If you are installing `hosts` manually,\n[completion can be enabled with a few commands](etc/README.md).\n\n## Usage\n\n### Listing Entries\n\n`hosts` with no arguments lists the entries in the system's hosts file:\n\n```bash\n\u003e hosts\n127.0.0.1       localhost\n255.255.255.255 broadcasthost\n::1             localhost\nfe80::1%lo0     localhost\n```\n\n`hosts` called with a string or regular expression will search for entries\nthat match.\n\n```bash\n\u003e hosts localhost\n127.0.0.1   localhost\n::1         localhost\nfe80::1%lo0 localhost\n\n\u003e hosts '\\d\\d\\d'\n127.0.0.1         localhost\n255.255.255.255   broadcasthost\n```\n\n### Adding Entries\n\nTo add an entry, use `hosts add`:\n\n```bash\n\u003e hosts add 127.0.0.1 example.com\nAdded:\n127.0.0.1 example.com\n```\n\nRun `hosts` or `hosts list` to see the new entry in the list:\n\n```bash\n\u003e hosts\n127.0.0.1         localhost\n255.255.255.255   broadcasthost\n::1               localhost\nfe80::1%lo0       localhost\n127.0.0.1         example.com\n```\n\n### Removing Entries\n\nTo remove an entry, use `hosts remove`, which can take an IP\naddress, domain, or regular expression:\n\n```bash\n\u003e hosts remove example.com\nRemoving the following entries:\n127.0.0.1\texample.com\nAre you sure you want to proceed? [y/N] y\nRemoved:\n127.0.0.1\texample.com\n```\n\n### Blocking and Unblocking Domains\n\n`hosts` provides easy commands for blocking and unblocking domains with IPv4\nand IPv6 entries:\n\n```bash\n\u003e hosts block example.com\nAdded:\n127.0.0.1   example.com\nAdded:\nfe80::1%lo0 example.com\nAdded:\n::1         example.com\n\n\u003e hosts unblock example.com\nRemoved:\n127.0.0.1   example.com\nRemoved:\nfe80::1%lo0 example.com\nRemoved:\n::1         example.com\n```\n\n### Enabling / Disabling Entries\n\nAll entries are enabled by default. Disabiling an entry comments it out\nso it has no effect, but remains in the hosts file ready to be enabled\nagain.\n\n```bash\n\u003e hosts\n127.0.0.1         localhost\n255.255.255.255   broadcasthost\n::1               localhost\nfe80::1%lo0       localhost\n127.0.0.1         example.com\n\n\u003e hosts disable example.com\nDisabling:\n127.0.0.1\texample.com\n\n\u003e hosts\n127.0.0.1         localhost\n255.255.255.255   broadcasthost\n::1               localhost\nfe80::1%lo0       localhost\n\nDisabled:\n---------\n127.0.0.1         example.com\n\n\u003e hosts enable example.com\nEnabling:\n127.0.0.1\texample.com\n\n\u003e hosts\n127.0.0.1         localhost\n255.255.255.255   broadcasthost\n::1               localhost\nfe80::1%lo0       localhost\n127.0.0.1         example.com\n```\n\n### Backups\n\nCreate backups of your hosts file with `hosts backups create`:\n\n```bash\n\u003e hosts backups create\nBacked up to /etc/hosts--backup-20200101000000\n```\n\nList your backups with `hosts backups`. If you have existing hosts file\nbackups, `hosts` will include them:\n\n```bash\n\u003e hosts backups\nhosts--backup-20200101000000\nhosts.bak\n```\n\n`hosts backups compare` will open your hosts file with `diff`:\n\n```bash\n\u003e hosts backups compare hosts--backup-20200101000000\n--- /etc/hosts\t2020-01-01 00:00:00.000000000\n+++ /etc/hosts--backup-20200101000000\t2020-01-01 00:00:00.000000000\n@@ -8,3 +8,4 @@\n 255.255.255.255  broadcasthost\n ::1              localhost\n fe80::1%lo0      localhost\n+127.0.0.1        example.com\n```\n\nView a backup with `hosts backups show`:\n\n```bash\n\u003e hosts backups show hosts--backup-20200101000000\n##\n# Host Database\n#\n# localhost is used to configure the loopback interface\n# when the system is booting.  Do not change this entry.\n##\n127.0.0.1       localhost\n255.255.255.255 broadcasthost\n::1             localhost\nfe80::1%lo0     localhost\n127.0.0.1       example.com\n```\n\nRestore a backup with `hosts backups restore`. Before a backup is\nrestored, a new one is created to avoid data loss:\n\n```bash\n\u003e hosts backups restore hosts--backup-20200101000000\nBacked up to /etc/hosts--backup-20200102000001\nRestored from backup: hosts--backup-20200101000000\n```\n\n### Viewing and Editing `/etc/hosts` Directly\n\n`hosts file` prints the raw contents of `/etc/hosts`:\n\n```bash\n\u003e hosts file\n##\n# Host Database\n#\n# localhost is used to configure the loopback interface\n# when the system is booting.  Do not change this entry.\n##\n127.0.0.1       localhost\n255.255.255.255 broadcasthost\n::1             localhost\nfe80::1%lo0     localhost\n```\n\n`hosts edit` opens `/etc/hosts` in your editor:\n\n```bash\n\u003e hosts edit\n```\n\n### `--auto-sudo`\n\nWhen the `--auto-sudo` flag is used, all write operations that require\n`sudo` will automatically rerun the command using `sudo` when the current user\ndoes not have write permissions for the hosts file.\n\nTo have this option always enabled, add the following line to your shell\nconfiguration (`.bashrc`, `.zshrc`, or similar):\n\n```bash\nalias hosts=\"hosts --auto-sudo\"\n```\n\n## Help\n\n```text\nUsage:\n  hosts [\u003csearch string\u003e]\n  hosts add \u003cip\u003e \u003chostname\u003e [\u003ccomment\u003e]\n  hosts backups [create | (compare | delete | restore | show) \u003cfilename\u003e]\n  hosts block \u003chostname\u003e...\n  hosts completions (check | install [-d | --download] | uninstall)\n  hosts disable (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e)\n  hosts disabled\n  hosts edit\n  hosts enable (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e)\n  hosts enabled\n  hosts file\n  hosts list [enabled | disabled | \u003csearch string\u003e]\n  hosts search \u003csearch string\u003e\n  hosts show (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e)\n  hosts subcommands [--raw]\n  hosts remove (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e) [--force]\n  hosts unblock \u003chostname\u003e...\n  hosts --auto-sudo\n  hosts -h | --help\n  hosts --version\n\nOptions:\n  --auto-sudo  Run write commands with `sudo` automatically.\n  -h --help    Display this help information.\n  --version    Display version information.\n\nHelp:\n  hosts help [\u003ccommand\u003e]\n```\n\nFor full usage, run:\n\n```text\nhosts help\n```\n\nFor help with a particular command, try:\n\n```text\nhosts help \u003ccommand name\u003e\n```\n\n## Subcommands\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#hosts-1\"\u003e(default)\u003c/a\u003e •\n  \u003ca href=\"#hosts-add\"\u003eadd\u003c/a\u003e •\n  \u003ca href=\"#hosts-backups\"\u003ebackups\u003c/a\u003e •\n  \u003ca href=\"#hosts-block\"\u003eblock\u003c/a\u003e •\n  \u003ca href=\"#hosts-completions\"\u003ecompletions\u003c/a\u003e •\n  \u003ca href=\"#hosts-disable\"\u003edisable\u003c/a\u003e •\n  \u003ca href=\"#hosts-disabled\"\u003edisabled\u003c/a\u003e •\n  \u003ca href=\"#hosts-edit\"\u003eedit\u003c/a\u003e •\n  \u003ca href=\"#hosts-enable\"\u003eenable\u003c/a\u003e •\n  \u003ca href=\"#hosts-enabled\"\u003eenabled\u003c/a\u003e •\n  \u003ca href=\"#hosts-file\"\u003efile\u003c/a\u003e •\n  \u003ca href=\"#hosts-help\"\u003ehelp\u003c/a\u003e •\n  \u003ca href=\"#hosts-list\"\u003elist\u003c/a\u003e •\n  \u003ca href=\"#hosts-remove\"\u003eremove\u003c/a\u003e •\n  \u003ca href=\"#hosts-search\"\u003esearch\u003c/a\u003e •\n  \u003ca href=\"#hosts-show\"\u003eshow\u003c/a\u003e •\n  \u003ca href=\"#hosts-subcommands\"\u003esubcommands\u003c/a\u003e •\n  \u003ca href=\"#hosts-unblock\"\u003eunblock\u003c/a\u003e •\n  \u003ca href=\"#hosts-version\"\u003eversion\u003c/a\u003e\n\u003c/p\u003e\n\n### `hosts`\n\n```text\nUsage:\n  hosts [\u003csearch string\u003e]\n\nDescription:\n  List the existing IP / hostname pairs, optionally limited to a specified\n  state. When provided with a seach string, all matching enabled entries will\n  be printed.\n\n  Alias for `hosts list`\n```\n\n### `hosts add`\n\n```text\nUsage:\n  hosts add \u003cip\u003e \u003chostname\u003e [\u003ccomment\u003e]\n\nDescription:\n  Add a given IP address and hostname pair, along with an optional comment.\n\nExit status:\n  0   Entry successfully added.\n  1   Invalid parameters or entry exists.\n```\n\n### `hosts backups`\n\n```text\nUsage:\n  hosts backups\n  hosts backups create\n  hosts backups compare \u003cfilename\u003e\n  hosts backups delete  \u003cfilename\u003e\n  hosts backups restore \u003cfilename\u003e [--skip-backup]\n  hosts backups show    \u003cfilename\u003e\n\nSubcommands:\n  backups           List available backups.\n  backups create    Create a new backup of the hosts file.\n  backups compare   Compare a backup file with the current hosts file.\n  backups delete    Delete the specified backup.\n  backups restore   Replace the contents of the hosts file with a\n                    specified backup. The hosts file is automatically\n                    backed up before being overwritten unless the\n                    '--skip-backup' flag is specified.\n  backups show      Show the contents of the specified backup file.\n\nDescription:\n  Manage backups.\n\nExit status:\n  0   Success.\n  1   Invalid parameters or backup not found.\n```\n\n### `hosts block`\n\n```text\nUsage:\n  hosts block \u003chostname\u003e...\n\nDescription:\n  Block one or more hostnames by adding new entries assigned to `127.0.0.1`\n  for IPv4 and both `fe80::1%lo0` and `::1` for IPv6.\n\nExit status:\n  0   \u003chostname\u003e successfully blocked.\n  1   Invalid parameters or entry exists.\n```\n\n#### Blocklists\n\n- [jmdugan/blocklists](https://github.com/jmdugan/blocklists)\n- [notracking/hosts-blocklists](https://github.com/notracking/hosts-blocklists)\n\n### `hosts completions`\n\n```text\nUsage:\n  hosts completions (check | install [-d | --download] | uninstall)\n\nOptions:\n  -d, --download  Download the completion scripts and install.\n\nDescription:\n  Manage completion scripts. For more information, visit:\n  https://github.com/xwmx/hosts/blob/master/etc/README.md\n\nExit status:\n  0   Completions successfully installed.\n  1   Invalid parameters or other error.\n```\n\n### `hosts disable`\n\n```text\nUsage:\n  hosts disable (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e)\n\nDescription:\n  Disable one or more entries based on a given ip address, hostname, or\n  search string.\n\nExit status:\n  0   Entry successfully disabled.\n  1   Invalid parameters or entry not found.\n```\n\n### `hosts disabled`\n\n```text\nUsage:\n  hosts disabled\n\nDescription:\n  List all disabled entries. This is an alias for `hosts list disabled`.\n\nExit status:\n  0   One or more disabled entries found.\n  1   Invalid parameters or no disabled entries found.\n```\n\n### `hosts edit`\n\n```text\nUsage:\n  hosts edit\n\nDescription:\n  Open the /etc/hosts file in your $EDITOR.\n```\n\n### `hosts enable`\n\n```text\nUsage:\n  hosts enable (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e)\n\nDescription:\n  Enable one or more disabled entries based on a given ip address, hostname,\n  or search string.\n\nExit status:\n  0   Entry successfully enabled.\n  1   Invalid parameters or entry not found.\n```\n\n### `hosts enabled`\n\n```text\nUsage:\n  hosts enabled\n\nDescription:\n  List all enabled entries. This is an alias for `hosts list enabled`.\n\nExit status:\n  0   One or more enabled entries found.\n  1   Invalid parameters or no enabled entries found.\n```\n\n### `hosts file`\n\n```text\nUsage:\n  hosts file\n\nDescription:\n  Print the entire contents of the /etc/hosts file.\n```\n\n### `hosts help`\n\n```text\nUsage:\n  hosts help [\u003ccommand\u003e]\n\nDescription:\n  Display help information for hosts or a specified command.\n```\n\n### `hosts list`\n\n```text\nUsage:\n  hosts list [enabled | disabled | \u003csearch string\u003e]\n\nDescription:\n  List the existing IP / hostname pairs, optionally limited to a specified\n  state. When provided with a seach string, all matching enabled entries will\n  be printed.\n\nExit status:\n  0   One or more matching entries found.\n  1   Invalid parameters or entry not found.\n```\n\n### `hosts remove`\n\n```text\nUsage:\n  hosts remove (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e) [--force]\n  hosts remove \u003cip\u003e \u003chostname\u003e\n\nOptions:\n  --force  Skip the confirmation prompt.\n\nDescription:\n  Remove one or more entries based on a given IP address, hostname, or search\n  string. If an IP and hostname are both provided, only entries matching the\n  IP and hostname pair will be removed.\n\nExit status:\n  0   Entry successfully removed.\n  1   Invalid parameters or entry not found.\n```\n\n### `hosts search`\n\n```text\nUsage:\n  hosts search \u003csearch string\u003e\n\nDescription:\n  Search entries for \u003csearch string\u003e.\n\nExit status:\n  0   One or more matching entries found.\n  1   Invalid parameters or entry not found.\n```\n\n### `hosts show`\n\n```text\nUsage:\n  hosts show (\u003cip\u003e | \u003chostname\u003e | \u003csearch string\u003e)\n\nDescription:\n  Print entries matching a given IP address, hostname, or search string.\n\nExit status:\n  0   One or more matching entries found.\n  1   Invalid parameters or entry not found.\n```\n\n### `hosts subcommands`\n\n```text\nUsage:\n  hosts subcommands [--raw]\n\nOptions:\n  --raw  Display the subcommands list without formatting.\n\nDescription:\n  Display the list of available subcommands.\n```\n\n### `hosts unblock`\n\n```text\nUsage:\n  hosts unblock \u003chostname\u003e...\n\nDescription:\n  Unblock one or more hostnames by removing the entries from the hosts file.\n\nExit status:\n  0   \u003chostname\u003e successfully unblocked.\n  1   Invalid parameters or entry not found\n```\n\n### `hosts version`\n\n```text\nUsage:\n  hosts (version | --version)\n\nDescription:\n  Display the current program version.\n```\n\n## Tests\n\nTo run the [test suite](test), install [Bats](https://github.com/sstephenson/bats) and\nrun `bats test` in the project root directory.\n\n---\n\u003cp align=\"center\"\u003e\n  Copyright (c) 2015-present William Melody • See LICENSE for details.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/xwmx/hosts\"\u003egithub.com/xwmx/hosts\u003c/a\u003e\n\u003c/p\u003e\n","funding_links":["https://github.com/sponsors/xwmx","https://paypal.me/WilliamMelody"],"categories":["Shell","Networking"],"sub_categories":["Kubernetes"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwmx%2Fhosts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxwmx%2Fhosts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwmx%2Fhosts/lists"}