{"id":13582357,"url":"https://github.com/txn2/txeh","last_synced_at":"2026-02-09T01:11:22.176Z","repository":{"id":44404614,"uuid":"170821475","full_name":"txn2/txeh","owner":"txn2","description":"Go library and CLI utility for /etc/hosts management.","archived":false,"fork":false,"pushed_at":"2024-01-30T08:27:31.000Z","size":266,"stargazers_count":326,"open_issues_count":1,"forks_count":41,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-14T15:56:56.754Z","etag":null,"topics":["binary","brew","developer-tools","devops","dns","golang","homebrew","hostsfile","library","network","networking","sysadmin","utility"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/txn2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-15T07:35:54.000Z","updated_at":"2025-03-20T21:54:22.000Z","dependencies_parsed_at":"2024-01-19T08:14:17.924Z","dependency_job_id":"4e471387-dd15-45e1-99e7-a4498c818d17","html_url":"https://github.com/txn2/txeh","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txn2%2Ftxeh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txn2%2Ftxeh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txn2%2Ftxeh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txn2%2Ftxeh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/txn2","download_url":"https://codeload.github.com/txn2/txeh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319715,"owners_count":22051072,"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":["binary","brew","developer-tools","devops","dns","golang","homebrew","hostsfile","library","network","networking","sysadmin","utility"],"created_at":"2024-08-01T15:02:38.241Z","updated_at":"2026-02-06T06:03:23.293Z","avatar_url":"https://github.com/txn2.png","language":"Go","readme":"![txeh - /etc/hosts mangement](logo.png)\n\n\n# Etc Hosts Management Utility \u0026 Go Library\n\n[![CI](https://github.com/txn2/txeh/actions/workflows/ci.yml/badge.svg)](https://github.com/txn2/txeh/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/txn2/txeh/branch/master/graph/badge.svg)](https://codecov.io/gh/txn2/txeh)\n[![Go Report Card](https://goreportcard.com/badge/github.com/txn2/txeh)](https://goreportcard.com/report/github.com/txn2/txeh)\n[![Go Reference](https://pkg.go.dev/badge/github.com/txn2/txeh.svg)](https://pkg.go.dev/github.com/txn2/txeh)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/txn2/txeh/badge)](https://securityscorecards.dev/viewer/?uri=github.com/txn2/txeh)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n**[Documentation](https://txeh.txn2.com)** | **[Go Reference](https://pkg.go.dev/github.com/txn2/txeh)** | **[Releases](https://github.com/txn2/txeh/releases)**\n\n### /etc/hosts Management\n\nIt is easy to open your [/etc/hosts] file in text editor and add or remove entries. However, if you make heavy use of [/etc/hosts] for software development or DevOps purposes, it can sometimes be difficult to automate and validate large numbers of host entries.\n\n**txeh** was initially built as a golang library to support [kubefwd](https://github.com/txn2/kubefwd), a Kubernetes port-forwarding utility utilizing [/etc/hosts] heavily, to associate custom hostnames with multiple local loopback IP addresses and remove these entries when it terminates.\n\nA computer's [/etc/hosts] file is a powerful utility for developers and system administrators to create localized, custom DNS entries. This small go library and utility were developed to encapsulate the complexity of working with [/etc/hosts] directly by providing a simple interface for adding and removing entries in a [/etc/hosts] file.\n\n**Features:**\n- Thread-safe operations (mutex-protected for concurrent use)\n- IPv4 and IPv6 support\n- CIDR range operations for bulk add/remove\n- Preserves comments and file formatting\n- Cross-platform (Linux, macOS, Windows)\n\n## txeh Utility\n\n### Install\n\nMacOS [homebrew](https://brew.sh) users can `brew install txn2/tap/txeh`, otherwise see [releases](https://github.com/txn2/txeh/releases) for packages and binaries for a number of distros and architectures including Windows, Linux and Arm based systems.\n\n#### Install with go install\n\nWhen installing with Go please use the latest stable Go release. At least go1.24 or greater is required.\n\nTo install use: `go install github.com/txn2/txeh/txeh@master`\n\nIf you are building from a local source clone, use `go install ./txeh` from the top-level directory of the clone.\n\ngo install will typically put the txeh binary inside the bin directory under go env GOPATH, see Go’s [Compile and install packages and dependencies](https://golang.org/cmd/go/#hdr-Compile_and_install_packages_and_dependencies) for more on this. You may need to add that directory to your $PATH if you encounter the error `txeh: command not found` after installation, you can find a guide for adding a directory to your PATH at https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7#file-path-md.\n\n#### Compile and run from source\n\ndependencies are vendored:\n```\ngo run ./txeh/txeh.go\n```\n\n### Use\n\nThe txeh CLI application allows command line or scripted access to /etc/hosts file modification.\n\n**Example CLI Usage**:\n```bash\n _            _\n| |___  _____| |__\n| __\\ \\/ / _ \\ '_ \\\n| |_ \u003e  \u003c  __/ | | |\n \\__/_/\\_\\___|_| |_|\n\nAdd, remove and re-associate hostname entries in your /etc/hosts file.\nRead more including usage as a Go library at https://github.com/txn2/txeh\n\nUsage:\n  txeh [flags]\n  txeh [command]\n\nAvailable Commands:\n  add         Add hostnames to /etc/hosts\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  list        List hostnames or IP addresses\n  remove      Remove a hostname or ip address\n  show        Show hostnames in /etc/hosts\n  version     Print the version number of txeh\n\n\nFlags:\n  -d, --dryrun                   dry run, output to stdout (ignores quiet)\n  -h, --help                     help for txeh\n  -m, --max-hosts-per-line int   Max hostnames per line (0=auto, -1=unlimited, \u003e0=explicit)\n  -q, --quiet                    no output\n  -r, --read string              (override) Path to read /etc/hosts file.\n  -w, --write string             (override) Path to write /etc/hosts file.\n```\n\n\n```bash\n# point the hostnames \"test\" and \"test.two\" to the local loopback\nsudo txeh add 127.0.0.1 test test.two\n\n# remove the hostname \"test\"\nsudo txeh remove host test\n\n# remove multiple hostnames\nsudo txeh remove host test test2 test.two\n\n# remove an IP address and all the hosts that point to it\nsudo txeh remove ip 93.184.216.34\n\n# remove multiple IP addresses\nsudo txeh remove ip 93.184.216.34 127.1.27.1\n\n# remove CIDR ranges\nsudo txeh remove cidr 93.184.216.0/24 127.1.27.0/28\n\n# quiet mode will suppress output\nsudo txeh remove ip 93.184.216.34 -q\n\n# dry run will print a rendered /etc/hosts with your changes without\n# saving it.\nsudo txeh remove ip 93.184.216.34 -d\n\n# use quiet mode and dry-run to direct the rendered /etc/hosts file\n# to another file\nsudo txeh add 127.1.27.100 dev.example.com -q -d \u003e hosts.test\n\n# specify an alternate /etc/hosts file to read. writing will\n# default to the specified read path.\ntxeh add 127.1.27.100 dev2.example.com -q -r ./hosts.test\n\n# specify a separate read and write path\ntxeh add 127.1.27.100 dev3.example.com -r ./hosts.test -w ./hosts.test2\n\n```\n\n## Comments\n\ntxeh supports inline comments on host entries, useful for tracking which tool or purpose added specific entries (e.g., docker, development environments).\n\n### How Comments Work\n\nComments use the standard hosts file format: `IP HOSTNAME [HOSTNAME...] # comment`\n\n**Key behavior:**\n- Comments are used for **grouping**: hosts with the same IP AND same comment are placed on the same line\n- Hosts added **without** a comment only match lines **without** a comment\n- Hosts added **with** a comment only match lines **with the same comment**\n- Comments are **never modified** on existing lines\n- If no matching line exists, a new line is created\n\n### CLI Usage\n\n```bash\n# Add host with a comment\nsudo txeh add 127.0.0.1 myapp --comment \"local development\"\n# Result: 127.0.0.1        myapp # local development\n\n# Add another host with the same comment (groups together)\nsudo txeh add 127.0.0.1 myapp2 --comment \"local development\"\n# Result: 127.0.0.1        myapp myapp2 # local development\n\n# Add host with a different comment (new line)\nsudo txeh add 127.0.0.1 api --comment \"staging environment\"\n# Result: 127.0.0.1        api # staging environment\n\n# Add host without a comment (only matches lines without comments)\nsudo txeh add 127.0.0.1 test\n# Result: goes to first 127.0.0.1 line that has NO comment, or creates new line\n```\n\n### Library Usage\n\n```go\n// Add hosts with a comment\nhosts.AddHostWithComment(\"127.0.0.1\", \"myapp\", \"local development\")\nhosts.AddHostsWithComment(\"127.0.0.1\", []string{\"svc1\", \"svc2\"}, \"my project services\")\n\n// Add hosts without a comment (original behavior)\nhosts.AddHost(\"127.0.0.1\", \"myhost\")\nhosts.AddHosts(\"127.0.0.1\", []string{\"a\", \"b\", \"c\"})\n```\n\n### Example Scenario\n\nStarting hosts file:\n```\n127.0.0.1        localhost\n127.0.0.1        app1 app2 # dev services\n```\n\n| Command | Result |\n|---------|--------|\n| `txeh add 127.0.0.1 app3 -c \"dev services\"` | app3 added to \"dev services\" line |\n| `txeh add 127.0.0.1 api -c \"staging env\"` | New line: `127.0.0.1 api # staging env` |\n| `txeh add 127.0.0.1 test` | test added to localhost line (no comment) |\n\n### Listing and Removing by Comment\n\nList all hosts with a specific comment:\n```bash\nsudo txeh list bycomment \"dev services\"\n```\n\nRemove all entries with a specific comment (removes entire lines):\n```bash\nsudo txeh remove bycomment \"dev services\"\n```\n\n### Modifying Comments\n\nComments are never modified on existing lines. To change a comment, remove the hosts first and re-add them with the new comment:\n\n```bash\n# Remove all entries with the old comment\nsudo txeh remove bycomment \"old comment\"\n\n# Re-add with the new comment\nsudo txeh add 127.0.0.1 app1 app2 --comment \"new comment\"\n```\n\n## txeh Go Library\n\n**Dependency:**\n```bash\ngo get github.com/txn2/txeh\n```\n\n**Example Golang Implementation**:\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/txn2/txeh\"\n)\n\nfunc main() {\n    // Load the system hosts file\n    hosts, err := txeh.NewHostsDefault()\n    if err != nil {\n        panic(err)\n    }\n\n    // Add hosts (without comments)\n    hosts.AddHost(\"127.100.100.100\", \"myapp\")\n    hosts.AddHost(\"127.100.100.101\", \"database\")\n    hosts.AddHosts(\"127.100.100.102\", []string{\"cache\", \"queue\", \"search\"})\n\n    // Add hosts with comments (for tracking/organization)\n    hosts.AddHostWithComment(\"127.100.100.200\", \"api.local\", \"development services\")\n    hosts.AddHostsWithComment(\"127.100.100.201\", []string{\"web.local\", \"admin.local\"}, \"frontend apps\")\n\n    // Query existing entries\n    addresses := hosts.ListAddressesByHost(\"myapp\", true)\n    fmt.Printf(\"myapp resolves to: %v\\n\", addresses)\n\n    hostnames := hosts.ListHostsByIP(\"127.100.100.102\")\n    fmt.Printf(\"Hosts at 127.100.100.102: %v\\n\", hostnames)\n\n    // List all hosts with a specific comment\n    devHosts := hosts.ListHostsByComment(\"development services\")\n    fmt.Printf(\"Dev service hosts: %v\\n\", devHosts)\n\n    // Remove entries\n    hosts.RemoveHost(\"database\")\n    hosts.RemoveHosts([]string{\"cache\", \"queue\"})\n    hosts.RemoveAddress(\"127.1.27.1\")\n    hosts.RemoveAddresses([]string{\"127.1.27.15\", \"127.1.27.14\"})\n\n    // Remove all entries with specific comments\n    hosts.RemoveByComment(\"frontend apps\")\n    hosts.RemoveByComments([]string{\"old environment\", \"deprecated\"})\n\n    // RemoveCIDRs returns an error (CIDR parsing can fail)\n    if err := hosts.RemoveCIDRs([]string{\"10.0.0.0/8\"}); err != nil {\n        panic(err)\n    }\n\n    // Preview changes\n    fmt.Println(hosts.RenderHostsFile())\n\n    // Save changes\n    err = hosts.Save()\n    if err != nil {\n        panic(err)\n    }\n    // Or save to a specific file: hosts.SaveAs(\"./custom.hosts\")\n}\n```\n\n## Build Release\n\nBuild test release:\n```bash\ngoreleaser --skip-publish --clean --skip-validate\n```\n\nBuild and release:\n```bash\nGITHUB_TOKEN=$GITHUB_TOKEN goreleaser --clean\n```\n\n### License\n\nApache License 2.0\n\n---\n\nOpen source by [Craig Johnston](https://twitter.com/cjimti), sponsored by [Deasil Works, Inc.](https://deasil.works/)\n\n[/etc/hosts]:https://en.wikipedia.org/wiki/Hosts_(file)\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxn2%2Ftxeh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftxn2%2Ftxeh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxn2%2Ftxeh/lists"}