nag

nag is a spoken command-line reminder. It can schedule a reminder relative to now or for the next occurrence of a clock time.

Install

The installer builds a release binary and installs a nag launcher plus its nag-bin companion. The launcher schedules reminders in the background, so your shell is immediately available again.

./install.sh                         # installs to ~/.local/bin
./install.sh /usr/local/bin          # choose an install directory explicitly
NAG_INSTALL_DIR=~/bin ./install.sh   # equivalent environment-variable form

Ensure the selected directory is on your PATH. Installing to /usr/local/bin may require elevated permissions. You need a Rust toolchain (cargo) to run the installer.

Usage

nag [--estimate] <in|at> <target> [message ...]
nag me [--pid]

The message may be quoted or supplied as multiple words. If it is omitted, nag says It is now <scheduled time>. The me command is provided by the installed background launcher; direct nag-bin and cargo run -- … invocations retain the scheduling-only interface.

Relative reminders

nag in 30 "Time to take a break"       # 30 minutes
nag in 1:10 "Stand up"                 # 1 hour, 10 minutes
nag in 0:01:30 "Short timer"           # 1 minute, 30 seconds

in accepts minutes, HH:MM, or HH:MM:SS. Minutes and seconds in colon-separated forms must be in 0..59; a duration must be greater than zero.

Clock-time reminders

nag at 9:55am "Meeting in five minutes"
nag at 22:55 "Go to bed"
nag at 10:55 "Go to bed"               # next 10:55, am or pm

at accepts H, H:MM, or either form with an am/pm suffix. Values with am/pm must use hours 1..12. Unsuffixed 0 and 13..23 are 24-hour times; unsuffixed 1..12 selects the next matching 12-hour clock time. This makes nag at 10:55 convenient whether it is currently morning or evening. If the requested time is exactly now, nag schedules the next occurrence.

Use an explicit am/pm suffix or 24-hour time when precision matters.

Upcoming reminders and cancellation

nag --estimate in 1:10
# 11:31am

nag in 30 "Check the oven"
# nagging @ 10:51am
# reminder pid: 12345

nag at 9am "Daily Standup"
nag me
# 09:00am        daily standup
# 10:51am        check the oven
# 2026-08-13 08:15am     tomorrow's reminder

nag me --pid
# 09:00am        12346   daily standup
# 10:51am        12345   check the oven

kill 12345

(The columns above are tab-separated.) nag me lists launcher-created reminders chronologically. Times are fixed-width and messages are lowercased for the list only; the spoken message is unchanged. Dates use YYYY-MM-DD and appear when a reminder is due after today. Add --pid to put the numeric process ID in the middle column. With no pending reminders, it prints No upcoming nags.

The installed launcher still prints each background process ID immediately, so kill <pid> cancels that reminder. Killed and completed reminders are removed the next time nag me scans the registry. Launcher metadata is stored privately under ${XDG_STATE_HOME:-$HOME/.local/state}/nag; NAG_STATE_DIR can select another directory. Reminders and their records do not survive a reboot.

Only reminders scheduled through the installed nag launcher appear in nag me. nag-bin and cargo run -- … remain foreground scheduling commands and do not register reminders.

Speech backends

• macOS uses the built-in say command.
• Linux tries spd-say, then espeak-ng, then espeak; install one of them and ensure an audio session is available.
• Windows uses Windows PowerShell and System.Speech.

A missing backend or a backend failure is reported by a foreground nag-bin invocation. The detached launcher cannot display errors that occur after it returns.