lazyntfy/man/lazyntfy.1

.\" lazyntfy(1) - a lazygit-style terminal client for ntfy
.TH LAZYNTFY 1 "2026-10-11" "lazyntfy 0.1.0" "User Commands"
.SH NAME
lazyntfy \- a lazygit-style terminal client for ntfy
.SH SYNOPSIS
.B lazyntfy
.RI [ options ]
.RI [ topic ...]
.SH DESCRIPTION
.B lazyntfy
is a terminal user interface for the
.BR ntfy (1)
pub\-sub notification service, laid out like
.BR lazygit (1):
topics in the left pane, messages in the middle pane, and the selected
message in the right pane.
.PP
It speaks the ntfy HTTP API directly, subscribing with
.B GET
.IR topic /json
and publishing with
.B POST
.IR topic .
When no topic is given on the command line it asks the server for the
account subscriptions, reserved topics, and ACL grants, then adds any
topics remembered from previous sessions. Short topic names are expanded
with
.IR default\-host .
.PP
Messages from Grafana and Alertmanager webhooks are summarized (status,
alert name, severity, and summary); the raw JSON is available with the
.B v
key. A message that is deleted or cleared on the server is removed from
the list as well.
.PP
When the connection drops,
.B lazyntfy
reconnects and sets the stream's
.B since
parameter to the newest event time it has already seen, so no message is
delivered twice.
.SH OPTIONS
.TP
.BI \-\-config " path"
Read the ntfy client configuration from
.IR path
instead of
.IR ~/.config/ntfy/client.yml .
.TP
.BI \-\-host " url"
Override
.I default\-host
from the configuration file.
.TP
.BI \-\-token " token"
Use
.I token
as a Bearer credential, overriding the configuration file.
.TP
.BI \-\-user " user[:password]"
Use HTTP basic authentication, overriding
.I default\-user
and
.I default\-password .
A token and a user are mutually exclusive; the last one given wins.
.TP
.BI \-\-since " value"
Replay window to request when a stream is opened. The value is
.B all
(the default), a duration such as
.BR 1h ,
a Unix timestamp, or a message id.
.TP
.B \-\-version
Print the version and exit.
.TP
.B \-\-help
Print a short usage summary and exit.
.SH KEYS
Keys act on the focused pane. Use
.B tab
or
.BR 1 ,
.BR 2 ,
.B 3
to change panes.
.TP
.B j ", " k ", " \(dqup\(dq ", " \(dqdown\(dq
Move within the focused pane..TP
.B g ", " G
Jump to the first or last item.
.TP
.B ctrl\-u ", " ctrl\-d
Page up or down.
.TP
.B enter
Descend: topics to messages to detail.
.TP
.B esc
Leave the detail pane, or clear an active filter.
.TP
.B /
Filter by title, body, tags, and message id.
.TP
.B r
Reconnect the streams.
.TP
.B p
Publish a message to the focused topic.
.TP
.B a
Subscribe to another topic for this session and remember it.
.TP
.B v
Toggle the raw JSON view of the selected message.
.TP
.B o
Open the selected message's click URL in the default browser.
.TP
.B ?
Show the in\-app help.
.TP
.B q
Quit.
.SH FILES
.TP
.I ~/.config/ntfy/client.yml
The ntfy client configuration read at startup. It supplies
.IR default\-host ,
.IR default\-token " / " default\-user " / " default\-password ,
and the
.I subscribe
list. Credentials are sent in the
.B Authorization
header and are never printed or written back.
.TP
.IR $XDG_DATA_HOME /lazyntfy/history.db
The SQLite database that remembers topics and messages between runs.
When
.B XDG_DATA_HOME
is unset it falls back to
.IR ~/.local/share/lazyntfy/history.db .
Credentials are never stored. History is best effort: if the file cannot
be opened the client still runs, it simply does not remember the session.
.SH ENVIRONMENT
.TP
.B XDG_DATA_HOME
Base directory for the history database.
.SH EXIT STATUS
.TP
.B 0
Success, including
.B \-\-help
and
.BR \-\-version .
.TP
.B 1
The terminal interface failed.
.TP
.B 2
Invalid arguments or configuration.
.SH SEE ALSO
.BR ntfy (1),
.BR curl (1)
.PP
The ntfy HTTP API:
.IR https://docs.ntfy.sh/publish/ .
.SH LICENSE
GNU General Public License, version 3 or later.