atrun(8) for the rat race
a month ago

1c20d50 Manual update by job 941628

a month ago

#🐀 ratrun builds.sr.ht build statusLicence

atrun(8) for the rat race.

#Manual (PDF)

(mandoc really does a number on the HTML output, I recommend the PDF)


Four components.

ratrun (pp. 6-7) reads calendar-style events in a trivial format (or a subset of iCal) from ~/.ratrun, sends reminders when reminders expire, and when they all do, moves the events to ~/.ratrun/old.

rerat (pp. 8-9) reads expired events in ~/.ratrun/old and either moves them back to ~/.ratrun, if they have a note to do so, moves them to a specified archive, or does nothing.

rat (pp. 1-3) can be used as a conversational scheduler.

For reminders, iCalendar subset is expected to be compatible with commercial calendaring systems (Outlook, Teams, GCalendar, Evolution, &c.), but see errata in ratrun.ics(7) (p. 4). For periodic events, iCalendar RRULE seems unemulatable, cf. rerat.ics(7) (p. 5), but normal rerat configuration works.


The /etc/default/ratrun preset and requirements therefor will only change between numbered versions.

The actual event format is committed in perpetuity, as are the semantics of individual config keys.


Needs GNU make, AWK, mandoc (linting and HTML manuals only, MANDOC=: to disable), and shellcheck (for shell wrappers, SHELLCHECK=: to disable), and gettext (only if you want localisation).

Set RATRUN_RUNNERDIR= (default of /usr/libexec/, used only by manuals) if you'll put ratrun/rerat in the PATH.

VOREUTILS_VERSION and VOREUTILS_DATE are derived from the git HEAD by default.



  • ${CMDDIR?-out/cmd}/ratrun and ${CMDDIR?-out/cmd}/rerat somewhere compatible with RATRUN_RUNNERDIR,
  • ${CMDDIR?-out/cmd}/rat in the $PATH somewhere,
  • ratrun in /etc/default,
  • ${LOCDIR?-out/locale} in /usr/share (or $TEXTDOMAINDIR),
  • ${MANDIR?-out/man} in /usr/share (or wherever your $MANPATH reaches).

Adjust /etc/default/ratrun to suit your mail setup, and both it and your cron config to run ratrun -a to suit your (users') tastes.


  • MAWK or stronger (probably hard-POSIX AWK would suffice, but I haven't tried) – for iCal support
  • /usr/share/zoneinfo (tzdata) – for iCal support
  • setpriv(1) (util-linux) – for -a, it'd be easy to replace with an equivalent
  • flock(1) (util-linux) – for event and rerat archive locking to prevent funny moments; you could shim it out if you're brave
  • mail(1) (4.4BSD-compatible, default config is mailutils, see preset for s-nail; there's security (well, "users using ratrun as atrun") considerations about (~) escapes)
  • date(1) with useful -d and mktemp(1) (callable as -t pref.XXX, but that's all of them post-2001)
  • POSIX-compatible shell (bash in POSIX mode (default when run with argv[0]=sh) qualifies, god save you if you run it out of POSIX mode though)


  • [n]gettext(1) (gettext-base) – shimmed out, but that removes localisation
  • getent(1) (libc-bin) – polyfilled to interrogate /etc/{passwd,group} instead

#From Debian repository

The following line in /etc/apt/sources.list or equivalent:

deb [signed-by=/etc/apt/keyrings/nabijaczleweli.asc] https://debian.nabijaczleweli.xyz sid main

With my PGP key (the two URLs are interchangeable):

sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://debian.nabijaczleweli.xyz/nabijaczleweli.gpg.key
sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://nabijaczleweli.xyz/pgp.txt

(you may need to create /etc/apt/keyrings on apt <2.4.0 (≤bullseye) manually).

Then the usual

sudo apt update
sudo apt install ratrun

will work.

See the repository README or the source package for more information.


Post to the tracker (~nabijaczleweli/ratrun@todo.sr.ht, preferable for bugs), the list (~nabijaczleweli/ratrun@lists.sr.ht, preferable for opinions and patches), or me directly (now with Platform integration!).

Not picky about patches — inline, attachment, and a git link and ref to pull are fine — just please include the repo name in the subject prefix.


All contents of this repository are subject to the 0-clause BSD licence.

#Special thanks

To Cicada for his Francophone insights.

To all who support further development on Patreon, in particular:

  • Embark Studios
  • ThePhD
  • Lars Strojny
  • EvModder