phg/hosts
0
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions
hosts/README.md

4.8 KiB
Raw Blame History

hosts

A keyboard-first terminal application for inspecting and editing /etc/hosts on macOS and Linux.

Warning

hosts is alpha software. It can replace a system file using sudo, and several recovery and persistence workflows still have known limitations. Read the user guide before entering Privileged Mode.

The hosts terminal interface

What it does

  • Browses, searches, and sorts active and inactive Host Entries.
  • Filters Host Entries by status, entry type, DNS resolution state, and search fields.
  • Hides or shows protected localhost and broadcasthost Default Entries.
  • Adds, edits, deletes, activates, deactivates, and reorders Host Entries.
  • Creates DNS Entries and manually refreshes their resolved IP addresses.
  • Gates every /etc/hosts mutation behind an explicit Privileged Mode.
  • Creates a timestamped Pre-edit Backup before Privileged Mode begins.
  • Restores the current session's Pre-edit Backup after explicit confirmation.
  • Supports undo and redo during the current Privileged Mode session.
  • Exports Host Entries as hosts, JSON, or CSV files. In Privileged Mode, imports can add Host Entries or replace the Hosts File after confirmation.

The application starts in Read-only Mode. Default Entries cannot be edited, deleted, activated, deactivated, or moved.

See Accessibility and terminal compatibility for the supported keyboard and terminal baseline, plus known assistive-technology limitations.

Requirements

  • macOS or Linux with /etc/hosts and sudo
  • Python 3.13 or newer
  • uv

The project is designed for macOS and Linux, but does not yet publish a tested platform matrix.

Run

The normal user entry point runs the current revision from the canonical Forgejo repository:

uvx git+https://git.s1q.dev/phg/hosts.git

Caution

This command follows the repository's default branch because the project does not yet publish versioned releases. Review the current project state and known limitations before granting sudo access.

Press Ctrl+E to enter Privileged Mode. The application uses an existing sudo authorization or displays a temporary authentication notice before returning control of the terminal to sudo and its configured PAM authentication method. It then creates a Pre-edit Backup before enabling changes. hosts never collects or handles authentication credentials.

Start with the user guide for the complete workflow, including persistence behavior and manual recovery.

Essential keys

Key Action
Up / Down Select a Host Entry
Ctrl+E Enter or leave Privileged Mode
b Review and restore the session Pre-edit Backup
n Add a Host Entry
Shift+N Add a Host Entry based on the selected Host Entry (N fallback without enhanced keyboard support; Caps Lock also triggers it)
e Open the selected Host Entry in the Entry Editor
d Delete the selected Host Entry
Space Activate or deactivate the selected Host Entry
Ctrl+S Save the current in-memory state
Ctrl+F Open advanced filters
Ctrl+X Export Host Entries (hosts, JSON, or CSV)
Ctrl+O Import Host Entries from hosts, JSON, or CSV (Privileged Mode)
? Show help
q or Ctrl+C Quit

Mutating keys work only in Privileged Mode. See the complete key reference for navigation, sorting, DNS refresh, movement, undo, and redo.

Safety and known limitations

  • Reloading discards unsaved in-memory state.
  • The TUI can restore only the Pre-edit Backup associated with the current Privileged Mode session; it does not list old backups or manage retention.
  • Leaving Privileged Mode clears the application's session state but does not alter the user's cached sudo timestamp.
  • Serialization preserves Host Entries and comments semantically, but normalizes spacing, comment placement, and blank lines. It is not a byte-for-byte round trip.

Read Persistence and recovery before making system-file changes.

Develop and contribute

Clone the repository for development:

git clone https://git.s1q.dev/phg/hosts.git
cd hosts
mise install
mise run sync
mise run app

mise installs the locked Python and uv versions and provides the project's development tasks.

See CONTRIBUTING.md for code boundaries, safety contracts, tests, linting, and documentation expectations. Domain language lives in CONTEXT.md, and consequential design decisions live in docs/adr/.

Report bugs and request features in the Forgejo issue tracker.

License

Licensed under the MIT License.