RAT(1)

SYNOPSIS

DESCRIPTION

Asks the user for:

when something happens,
what the occasion is,
when they want to be reminded about it,
additional data they want to remember verbatim,

in that order, then schedules it for delivery via ratrun(8), which will conveniently mail them this information at decreasing intervals to the time of the event.

This data may be incrementally partially satisfied via the arguments, instead.

when is in date -d format. If you specify it in a less-committal "next thursday"- or "tomorrow 15:00"-style format, which would change on each scan, you may want to prefix it with a ‘%’ to save it as a concrete time à la "2022-11-02T04:44+01:00" relative to now. The date and time of the event in a human-readable format are always listed on the standard output stream.

event is used as a file name (but slashes are massaged out to underscores, and, if required, -when and -%when are appended to prevent clashes) and is part of the Subject: in reminder mails.

reminders are only used if they start with a digit, otherwise the argument is subsumed by the body. In addition to the normal Reminders, each field may be a clock time (any date -d format, but clock time pairs well with a clock when).

body arguments are pasted together with spaces.

Non-interactively (if the standard input stream is not a teletype), no input is read, so empty reminders and body are assumed, and when and event are required.

If any options are specified, they engage rerat(8) for either scheduling a periodic reminder (-rm) or archiving the event when it expires (-aA):

-r,: in Reminders format, specifies the time between instances of the event and
-m: limits how many times the event will fire overall, while
-a,: in Reminders format, is the time after the event date after which it should be archived, and
-A: sets the file to archive to under ~/.ratrun/old/.
-v: sets verbose (you'll be mailed when the event is re-scheduled or archived), and
-R: just adds a blank "rerat:" line.

In all cases, ! overrides to default — no re-scheduling, no limit, or no archiving, respectively.
-A is a date(1) format string applied to the event date; the default is ".old".

The numeric options are used verbatim, if in the correct format; otherwise:

-r: may also be a date -d-format date, which becomes the second occurrence of the event, from which the period is derived; if
-m: is a date -d-format date, it's the final ocurrence of the event, with the repeat count rounded up (such that, in most cases, specifying just the day is sufficient to get what you want); if
-a: is a date -d-format date, it's the exact time to archive the event.

In addition to the date and time of the event, the recurrence and archival configuration is listed, if rerat(8) will process this file after it expires — this also takes into account your current default configuration: even if you didn't specify any options, if all is set, the event will still be subjected to processing, for example.

Reminders

Start with a digit, are decimal integers, and optionally end with a recursively-expanded multiplicative suffix:

mo	=	4	wk
wk	=	7	d
yr	=	365	d
d	=	24	h
h	=	60	m
m	=	60
s	=	1

in this order, i.e. 10h = 600m = 36000 (= 36000s).

They correspond to the minimal time before the event, in seconds, to send a reminder — i.e. for reminders "3600 60 0" (equiv. "1h 1m 0"), a mail will be sent no sooner than an hour, a minute, and at the time of the event.

SIGNALS

SIGHUP, SIGINT, SIGQUIT, and SIGTERM are caught, and the in-progress event discarded.

ENVIRONMENT

RATRUN_REMINDERS: System-wide default list of reminders. Overriden per-user with .reminders and per-event with reminders.
RERAT_DEFAULT: The default set of configuration words. Overriden per-user with .rerat and per-event with "rerat:" lines.
CONFDIR: Replaces "/etc/default" below.

FILES

/etc/default/ratrun: Sourced at the top.
~/.ratrun/: Scheduled events go here.
~/.ratrun/old/: And the ones for which all reminders were sent end up here.
~/.ratrun/.reminders: Overrides RATRUN_REMINDERS, if present. One field-split line.
~/.ratrun/.nevermind: Never ask for per-event reminders if present.
~/.ratrun/.tz: If present, value exported as TZ at the top, cf. tzset(3). One line.
~/.ratrun/.prefix: Overrides the "ratrun:" subject prefix, if present. "🐀" and empty are good candidates. One line.
~/.ratrun/.rerat: Overrides RERAT_DEFAULT, if present, providing a default configuration for all processed events. One field-split line.

EXAMPLES

rat 12:00 call-robert 1h\ 0 bring up sales for q4 Happens on Mon 31 Oct 2022 12:00:00 CET or
$ rat

12:00
  call-robert 11:00\ 12:00 bring up sales for q4

rat: reminders normalised to 1h 0 Happens on Mon 31 Oct 2022 12:00:00 CET $ rat

18:30
  'meet henry in 201' ''

Happens on Mon 31 Oct 2022 18:30:00 CET or
$ rat Event date/time (start with % to canonicalise): 18:30 Happens on Mon 31 Oct 2022 18:30:00 CET Event: meet henry in 201 Reminders (clock times OK; empty = default (%s)): Enter body; ^D to finish ^D $ rat 2022-12-12T23:11 1yr-uptime "$(date; uptime)" Happens on Mon 12 Dec 2022 23:11:00 CET

Assuming a default reminder time of "30m", the first reminders from each of these will, respectively, produce the following messages:

Date: Mon, 31 Oct 2022 11:00:42 +0100
Subject: ratrun: in 1h / on 12:00: call-robert

bring up sales for q4

and

Date: Mon, 31 Oct 2022 18:00:21 +0100
Subject: ratrun: in 30m / on 18:30: meet henry in 201

and

Date: Mon, 12 Dec 2022 22:41:12 +0100
Subject: ratrun: in 30m / on 23:11 (2022-12-12T23:11): 1yr-uptime

Mon 31 Oct 21:00:54 CET 2022
 21:00:54 up 322 days, 12:09,  4 users,  load average: 1.28, 0.69, 0.52

To archive the call with Robert after a month to the default (configured) archive file:

rat -a 1mo

12:00
  call-robert 1h\ 0 bring up sales for q4

Happens on Mon 31 Oct 2022 12:00:00 CET Will be archived in ~/.ratrun/old/.old on Mon 28 Nov 2022 12:00:00 CET or, as the case may be with archive-name=.'%y-Q%q in ~/.ratrun/.rerat, Will be archived in ~/.ratrun/old/.'22-Q4 on Mon 28 Nov 2022 12:00:00 CET

To instead make the meeting with Henry weekly:

rat -r 1wk

18:30
  'meet henry in 201' ''

Happens on Mon 31 Oct 2022 18:30:00 CET Will be re-scheduled ad infinitum; next time: Mon 07 Nov 2022 18:30:00 CET

(in both cases, the options can be added to both invocations).

Schedule a daily reminder for two weeks, starting tomorrow at 9pm:

$ rat -r 1d -m 14 '%tomorrow 21:00' chrzęść ''
Happens on Sun 08 Jan 2023 21:00:00 CET
Will be re-scheduled 13 times; next time: Mon 09 Jan 2023 21:00:00 CET; last time: Sat 21 Jan 2023 21:00:00 CET
or, equivalently:
$ rat -r '2023-01-09 21:00' -m 2023-01-21 '2023-01-08 21:00' chrzęść ''
&c.

NAME