336 lines
8.2 KiB
Markdown
336 lines
8.2 KiB
Markdown
nag, a bash script for setting one-off or repeating alarms with natural language
|
|
|
|
`nag` typically requires a cron daemon or systemd-timer to be available. On the first alarm set, `nag` will prompt to install whichever is relevant for your system. The timer will then invoke `nag check` on an interval, which checks for alarms that are due to go off, and triggers them as appropritate. By default `notify-send` is used, but the command triggered can be overriden with `NAG_CMD` to anything you like.
|
|
|
|
`nag` attempts to use something close to natural language. You can `nag [at] 2pm` for a one-off alarm at 2pm, or `nag every 2pm` for an alarm every 2pm. To delete an alarm, `nag stop` it, or to just skip one instance `nag skip`. If it's a one-off alarm being skipped, that's the same as just stopping it. If you want to keep an alarm from triggering for a duration, like during a week off, you can `nag snooze` it; that'll stop it triggering entirely. For just silencing the sound, `nag mute` instead.
|
|
|
|
Alarms can be tagged with `nag tag <id> <tags...>`, and all alarms of a tag can be listed with `nag tag <tag>`. When you `stop`, `skip`, `snooze`, or `mute` an alarm, you can either operate on `all` alarms, a specific id, or a specific tag. For example, `nag snooze work "until next Tuesday"`, or `nag mute all`.
|
|
|
|
`un-` commands work with all of the above. You can `nag unskip` a skipped alarm to bring it back to the next date. For example, if you skip your Friday alarm by mistake, `nag unskip` will find the next Friday and set the next expiration to whenever that is.
|
|
|
|
Time parsing is done with `date -d`, so it supports a decent array of formats:
|
|
- Times of day (15:30, 3:30pm, 3pm, noon, teatime)
|
|
- Calendar dates (2025-12-25, 25 Dec 2025, Dec 25)
|
|
- Combined (tomorrow 9am, next monday 15:30)
|
|
- Relative days (now, today, tomorrow, next week)
|
|
- Relative times (+1 hour, 30 minutes, +1 day)
|
|
- Ordinal dates (first monday, third friday of next month)
|
|
- Time zones (15:30 UTC, 3pm PST)
|
|
- ISO 8601 (2025-12-25T15:30:00)
|
|
- Epoch (@1735138200)
|
|
|
|
Rules for `nag every` are:
|
|
- hourly (h, hr, hours, hourly)
|
|
- daily (d, days, daily)
|
|
- weekly (week, weekly)
|
|
- monthly (month, months, monthly)
|
|
- yearly (year, years, yearly)
|
|
- weekday (weekday, weekdays)
|
|
- weekend (weekend, weekends)
|
|
- specific weekdays (mon, monday, mondays, etc.)
|
|
|
|
e.g. `nag every weekday midday "Take a break for dinner."`
|
|
|
|
```text
|
|
Usage:
|
|
nag list all alarms
|
|
nag <time> <message...> one-shot alarm
|
|
nag every <rules> <time> <message...> repeating alarm
|
|
nag stop <all|id|tag> delete alarm(s)
|
|
nag skip <all|id|tag> skip next occurrence(s)
|
|
nag unskip <all|id|tag> reset to next occurrence
|
|
nag tag <id> <tags...> add tags to an alarm
|
|
nag tag <tag> list alarms with a tag
|
|
nag untag <id> <tags...> remove tags from an alarm
|
|
nag snooze <all|id|tag> [<duration>] snooze alarms
|
|
nag unsnooze <all|id|tag> unsnooze alarms
|
|
nag check check and fire due alarms
|
|
nag mute <all|tag> mute alarm sounds
|
|
nag unmute <all|tag> unmute alarm sounds
|
|
nag edit edit alarms file directly
|
|
nag help [<subcommand>] show help
|
|
nag version show version
|
|
|
|
Options:
|
|
-e Edit alarms file directly.
|
|
-f Skip all prompts.
|
|
--iso Show times as YYYY-MM-DD HH:MM:SS.
|
|
--epoch Show times as unix timestamps.
|
|
-v Show version.
|
|
|
|
Environment:
|
|
NAG_DIR Alarm storage directory (default: ~/.local/share/nag)
|
|
NAG_CMD Notification command (default: notify-send)
|
|
NAG_SOUND Sound file to play (default: freedesktop bell sound)
|
|
```
|
|
|
|
### Help
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#installation">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
<div align="center">
|
|
<a href="#nag-list"><code>list</code></a> ·
|
|
<a href="#nag-at"><code>at</code></a> ·
|
|
<a href="#nag-every"><code>every</code></a> ·
|
|
<a href="#nag-stop"><code>stop</code></a> ·
|
|
<a href="#nag-skip"><code>skip</code></a> ·
|
|
<a href="#nag-tag"><code>tag</code></a> ·
|
|
<a href="#nag-untag"><code>untag</code></a> ·
|
|
<a href="#nag-check"><code>check</code></a> ·
|
|
<a href="#nag-mute"><code>mute</code></a> ·
|
|
<a href="#nag-unmute"><code>unmute</code></a> ·
|
|
<a href="#nag-edit"><code>edit</code></a> ·
|
|
<a href="#nag-help"><code>help</code></a> ·
|
|
<a href="#nag-version"><code>version</code></a>
|
|
</div>
|
|
|
|
#### `nag list`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag list
|
|
|
|
Description:
|
|
List all alarms. This is the default when no subcommand is given.
|
|
```
|
|
|
|
#### `nag at`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag [at] <time> <message...>
|
|
|
|
Description:
|
|
Create a one-shot alarm. The "at" is optional. If the first argument
|
|
doesn't match any other subcommand of nag, it'll fallback to "at".
|
|
|
|
Examples:
|
|
nag 3pm take a break
|
|
nag at 3pm take a break
|
|
nag "tomorrow 9am" dentist appointment
|
|
```
|
|
|
|
#### `nag every`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag every <rules> <time> <message...>
|
|
|
|
Description:
|
|
Create a repeating alarm. Rules are comma-separated and case-insensitive.
|
|
|
|
Rules (and aliases):
|
|
hour (h, hourly) monday (mon, mondays)
|
|
day (d, daily) tuesday (tue, tuesdays)
|
|
week (weekly) wednesday (wed, wednesdays)
|
|
month (monthly) thursday (thurs, thursdays)
|
|
year (yearly) friday (fri, fridays)
|
|
weekday (weekdays) saturday (sat, saturdays)
|
|
weekend (weekends) sunday (sun, sundays)
|
|
|
|
Examples:
|
|
nag every weekday 9am standup meeting
|
|
nag every tue,thu 3pm team sync
|
|
nag every year "December 25" Christmas
|
|
```
|
|
|
|
#### `nag stop`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag stop <id|tag>
|
|
|
|
Description:
|
|
Stop an alarm by ID, or stop all alarms with a tag.
|
|
```
|
|
|
|
#### `nag skip`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag skip <id|tag>
|
|
|
|
Description:
|
|
Skip the next occurrence of a repeating alarm (reschedule without firing).
|
|
For one-shot alarms, this deletes them. With a tag, applies to all
|
|
matching alarms.
|
|
```
|
|
|
|
#### `nag tag`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag tag <id> <tags...> add tags to an alarm
|
|
nag tag <tag> list alarms with a tag
|
|
|
|
Description:
|
|
Add tags to an alarm by ID, or list all alarms matching a tag.
|
|
Tags must not be pure integers.
|
|
```
|
|
|
|
#### `nag untag`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag untag <id> <tags...>
|
|
|
|
Description:
|
|
Remove one or more tags from an alarm.
|
|
```
|
|
|
|
#### `nag check`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag check
|
|
|
|
Description:
|
|
Check for due alarms and fire them. Run automatically by a systemd
|
|
timer (every 15s) or cron (every 60s). Repeating alarms are
|
|
rescheduled. One-shot alarms are removed. Stale alarms older than
|
|
15 minutes are silently dropped or rescheduled without firing.
|
|
```
|
|
|
|
#### `nag mute`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag mute [<tag>]
|
|
|
|
Description:
|
|
Mute alarm sounds. With no argument, mutes all alarms globally.
|
|
With a tag, mutes only alarms with that tag.
|
|
```
|
|
|
|
#### `nag unmute`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag unmute [<tag>]
|
|
|
|
Description:
|
|
Unmute alarm sounds. With no argument, unmutes everything.
|
|
With a tag, unmutes only that tag.
|
|
```
|
|
|
|
#### `nag edit`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag ( edit | -e )
|
|
|
|
Description:
|
|
Open the alarms file in $EDITOR (falls back to $VISUAL, then vi).
|
|
```
|
|
|
|
#### `nag help`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag help [<subcommand>]
|
|
|
|
Description:
|
|
Display help information for nag or a specified subcommand.
|
|
```
|
|
|
|
#### `nag version`
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
```text
|
|
Usage:
|
|
nag ( version | -v )
|
|
|
|
Description:
|
|
Display the current program version.
|
|
```
|
|
|
|
### License
|
|
|
|
<p>
|
|
<sup>
|
|
<a href="#help">↑</a>
|
|
</sup>
|
|
</p>
|
|
|
|
MIT - see [LICENSE](LICENSE).
|