# 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.

![The hosts terminal interface](./images/user_interface.png)

## 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.

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

## 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 |
| `?` | 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).