128 lines
4.7 KiB
Markdown
128 lines
4.7 KiB
Markdown
# 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](docs/user-guide.md) before entering Privileged Mode.
|
|
|
|
|
|
|
|
## 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, and imports those formats in Privileged Mode.
|
|
|
|
The application starts in Read-only Mode. Default Entries cannot be edited,
|
|
deleted, activated, deactivated, or moved.
|
|
|
|
See [Accessibility and terminal compatibility](docs/accessibility.md) 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](https://docs.astral.sh/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:
|
|
|
|
```bash
|
|
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](docs/user-guide.md) 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](docs/user-guide.md#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](docs/user-guide.md#persistence-and-recovery)
|
|
before making system-file changes.
|
|
|
|
## Develop and contribute
|
|
|
|
Clone the repository for development:
|
|
|
|
```bash
|
|
git clone https://git.s1q.dev/phg/hosts.git
|
|
cd hosts
|
|
mise install
|
|
mise run sync
|
|
mise run app
|
|
```
|
|
|
|
[mise](https://mise.jdx.dev/) installs the locked Python and uv versions and
|
|
provides the project's development tasks.
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for code boundaries, safety contracts,
|
|
tests, linting, and documentation expectations. Domain language lives in
|
|
[CONTEXT.md](CONTEXT.md), and consequential design decisions live in
|
|
[`docs/adr/`](docs/adr/).
|
|
|
|
Report bugs and request features in the
|
|
[Forgejo issue tracker](https://git.s1q.dev/phg/hosts/issues).
|
|
|
|
## License
|
|
|
|
Licensed under the [MIT License](./LICENSE).
|