docs: expand the README and add the lazyntfy(1) man page
Document features, installation, usage, key bindings, configuration, history, development, and project layout. Add a complete man page covering options, keys, files, and exit status.
This commit is contained in:
@@ -1,2 +1,174 @@
|
||||
# lazyntfy
|
||||
|
||||
A [lazygit](https://github.com/jesseduffield/lazygit)-style terminal client for
|
||||
[ntfy](https://ntfy.sh): topics in the left pane, messages in the middle pane,
|
||||
and the selected message in the right pane.
|
||||
|
||||
```
|
||||
╭ topics ─────╮ ╭ messages ─────────────────╮ ╭ detail ───────────────╮
|
||||
│ ● alerts 12 │ │ 06-14 09:21 CRIT DiskFull │ │ CRITICAL │
|
||||
│ ○ backups │ │ 06-14 09:03 high Backup… │ │ DiskFull │
|
||||
│ ○ deploy │ │ 06-13 22:47 def Deploy… │ │ 2026-06-14 09:21:07 │
|
||||
│ │ │ │ │ mK3n9Qx… │
|
||||
│ │ │ │ │ │
|
||||
╰─────────────╯ ╰────────────────────────────╯ ╰───────────────────────╯
|
||||
lazyntfy alerts 12/12 ● connected ? help q quit
|
||||
```
|
||||
|
||||
lazyntfy talks to the ntfy HTTP API directly (`GET /topic/json` to subscribe,
|
||||
`POST /topic` to publish). It reads `~/.config/ntfy/client.yml` for credentials
|
||||
and subscriptions, groups topics that share a server and credentials onto one
|
||||
stream, and reconnects automatically — resuming from the newest event it has
|
||||
already seen so nothing is delivered twice.
|
||||
|
||||
## Features
|
||||
|
||||
- **lazygit-style layout** — topics, messages, and message detail in three panes.
|
||||
- **Account discovery** — with no topic on the command line it lists your
|
||||
subscriptions, reservations, and ACL grants.
|
||||
- **Alert-aware** — Grafana and Alertmanager webhook bodies are summarized
|
||||
(status, alert name, severity, summary); `v` shows the raw JSON.
|
||||
- **Persistent** — topics you add and the messages that arrive are stored in a
|
||||
small SQLite file and restored on the next start.
|
||||
- **Resilient** — reconnects with exponential backoff, honoring `message_delete`
|
||||
and `message_clear` events.
|
||||
- **Single binary, no CGo** — pure Go, including the SQLite driver.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Go 1.26 or newer (to build)
|
||||
- A reachable ntfy server
|
||||
|
||||
## Installation
|
||||
|
||||
### From source
|
||||
|
||||
```sh
|
||||
git clone https://src.panahifar.ir/ahp/lazyntfy.git
|
||||
cd lazyntfy
|
||||
make install # installs the binary and the man page under ~/.local
|
||||
```
|
||||
|
||||
`make install` honors `PREFIX` (default `~/.local`):
|
||||
|
||||
```sh
|
||||
make install PREFIX=/usr/local
|
||||
```
|
||||
|
||||
### With `go install`
|
||||
|
||||
```sh
|
||||
go install ./cmd/lazyntfy@latest # or: go install lazyntfy/cmd/lazyntfy
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
lazyntfy # topics from the account, their history, and client.yml
|
||||
lazyntfy alerts # one topic, expanded with default-host
|
||||
lazyntfy --since 1h alerts # replay the last hour
|
||||
lazyntfy --host https://ntfy.example alerts
|
||||
lazyntfy --token tk_xxx alerts
|
||||
lazyntfy --user name:pass alerts
|
||||
```
|
||||
|
||||
With no topic on the command line, lazyntfy asks the server for your account
|
||||
subscriptions, reserved topics, and ACL grants (`GET /v1/account` and, when
|
||||
allowed, `GET /v1/users`), then adds the topics remembered from previous
|
||||
sessions. You can always add a topic for the current session with `a`.
|
||||
|
||||
## Key bindings
|
||||
|
||||
Keys act on the focused pane. Use `tab` / `shift-tab` or `1` / `2` / `3` to
|
||||
change panes.
|
||||
|
||||
| Key | Action |
|
||||
| --- | --- |
|
||||
| `j` / `k`, arrows | move in the focused pane |
|
||||
| `g` / `G` | first / last |
|
||||
| `ctrl-u` / `ctrl-d` | page up / down |
|
||||
| `1` / `2` / `3` | focus topics, messages, detail |
|
||||
| `tab` / `shift-tab` | next / previous pane |
|
||||
| `enter` | topics → messages → detail |
|
||||
| `esc` | back from detail, or clear the filter |
|
||||
| `/` | filter title, body, tags, and id |
|
||||
| `r` | reconnect |
|
||||
| `p` | publish to the focused topic |
|
||||
| `a` | subscribe to another topic for this session |
|
||||
| `v` | toggle raw JSON |
|
||||
| `o` | open the message click URL |
|
||||
| `?` | help |
|
||||
| `q` | quit |
|
||||
|
||||
On a narrow terminal the detail pane is hidden until it is focused.
|
||||
|
||||
## Configuration
|
||||
|
||||
lazyntfy reads the official ntfy client configuration at
|
||||
`~/.config/ntfy/client.yml`:
|
||||
|
||||
```yaml
|
||||
default-host: https://ntfy.example
|
||||
default-token: tk_xxxxxxxxxxxxxxxx
|
||||
subscribe:
|
||||
- topic: alerts
|
||||
- topic: https://other.example/backups
|
||||
user: alice
|
||||
password: secret
|
||||
```
|
||||
|
||||
Positional topics on the command line replace the file's `subscribe` list.
|
||||
Credentials are sent in the `Authorization` header and are never printed or
|
||||
written back. See `man lazyntfy` for every flag.
|
||||
|
||||
## History and storage
|
||||
|
||||
Topics you add and the messages that arrive are kept in a small SQLite database
|
||||
at `$XDG_DATA_HOME/lazyntfy/history.db`
|
||||
(`~/.local/share/lazyntfy/history.db` by default), so the last session is
|
||||
restored on the next start. Each topic keeps its newest 1000 messages; expired
|
||||
messages are pruned on startup. Credentials are never written to the database —
|
||||
the current run's authentication is always used. History is best effort: if the
|
||||
file cannot be opened, the client still runs.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
make build # build ./lazyntfy
|
||||
make test # go test ./...
|
||||
make vet # go vet ./...
|
||||
make fmt # gofmt -w .
|
||||
make run TOPIC=alerts
|
||||
make man # install just the man page
|
||||
```
|
||||
|
||||
Run a single package's tests, for example:
|
||||
|
||||
```sh
|
||||
go test ./internal/history/...
|
||||
```
|
||||
|
||||
## Project layout
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `cmd/lazyntfy` | flags and program startup |
|
||||
| `internal/config` | `client.yml` plus CLI overrides |
|
||||
| `internal/history` | on-disk topics and messages (SQLite) |
|
||||
| `internal/ntfy` | HTTP subscribe, publish, reconnect |
|
||||
| `internal/store` | newest-first messages, delete, clear |
|
||||
| `internal/alert` | Grafana / Alertmanager summary |
|
||||
| `internal/theme` | Catppuccin adaptive palette |
|
||||
| `internal/textutil` | width-aware text wrapping and clipping |
|
||||
| `internal/tui` | Bubble Tea interface |
|
||||
| `man` | `lazyntfy(1)` man page |
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository and create a topic branch.
|
||||
2. Keep commits focused and conventional (`feat:`, `fix:`, `docs:`, …).
|
||||
3. Run `make fmt vet test` before opening a pull request.
|
||||
|
||||
## License
|
||||
|
||||
GNU General Public License, version 3 or later. See [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user