lazyntfy/README.md

lazyntfy

A lazygit-style terminal client for ntfy: 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

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):

make install PREFIX=/usr/local

With go install

go install ./cmd/lazyntfy@latest   # or: go install lazyntfy/cmd/lazyntfy

Usage

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:

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

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:

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.