How and why to use KAlarm from the command line

Marco Fioretti describes ways of using KAlarm to automate and customize alerts on your desktop from the command line.

Kalarm helps you to schedule reminders and tasks on your Linux desktop, thus making it much harder to forget appointments, work assignments, or simply running certain commands at the right moment. You may use KAlarm, for example, to prepare an email now, but only send it one day or week later, if for whatever reason you need to do so.

Besides being cute, friendly and very well documented in a simple style, KAlarm has several features that are either missing or more difficult to use in its pure-Unix, command-line-only ancestors, at and cron. KAlarm can:

  • Perform several actions when an alarm triggers:
    • display on screen, or speak, text messages or the output from some command
    • play audio files or display images
    • send email
    • quietly run many other commands
  • Create birthday reminders for all the people in your KAddressBook
  • Wake up your computer (if it supports Wake From Suspend) from suspension or hibernation
  • Help you create many similar alarms quickly through templates
  • Share alarm information in the standard iCalendar format with other applications and computers
  • Execute a pre-alarm action before deferred alarms trigger (from version 2.9.0)

The KAlarm handbook and several tutorials available online make its graphical interface even easier to use, but I want to talk about something else. What many users don't know, or consider uninteresting, is the fact that KAlarm can also be controlled from the command line.

This is cool, because it means that you can delegate entirely to your computer the creation of certain alarms! Here's when this may be useful, and how to do it.

Finding alarms on the Web

If you follow my column, you may have already known that you can download, extract, and analyze all sorts of information from Web pages using shell functions or, as I do, create dynamic news menus in OpenBox with pipe scripts, and download RSS feeds via a simple script.

You can use the same techniques to retrieve announcements of future events that you would like to follow and automatically pass them to KAlarm, which will then remind you of them at just the right moment.

For example, let's imagine that you like Italian contemporary music and, consequently, want to watch every live concert, documentary or talk show about it broadcast on radio or TV.

Since these days all TV and radio schedules are published online, putting together a script that tells KAlarm to remind you when there's one of those shows is relatively easy. The general flow of such a script, which would run periodically as a cron job, would be something like this:

  • Download Web page or RSS feed of TV or radio schedule
  • Examine each text entry in those files, and for every entry containing the keywords "Italy" and "music":
    • extract from that entry the time of that event
    • pass that time and the name of the event to KAlarm, as explained below
  • Done!

The way to extract the relevant text and time from the pages or feeds you download is explained in my other posts linked above. Here, let's look at how to create an alarm. The commands that make KAlarm pop up a window at a certain moment in the future have the following structure:

kalarm-t $TIME "ALARM TEXT"

The -t switch says when the alarm must trigger. The format of $TIME is [[[yyyy-]mm-]dd-]hh:mm [TZ], where TZ is the time zone. You must only specify enough fields to make the date non-ambiguous. If an alarm had to be issued at 9:30 am of day 10 of the current month, you'd only have to write -t 10-09:30. Other useful options you may add are:

  • -a: ask for acknowledgment of the alarm message
  • -b: beep when the message is displayed
  • -c $COLOR sets the background color
  • -f: path or URL of a text or image file containing the alarm message
  • -k: show the alarm as an event in KOrganizer
As an example, Figure A shows the result of running this command:
kalarm -c red -t 2012-05-10-10:28 "write post for Tech Republic" -k

Figure A

The only problem with calling KAlarm in this way is that the handbook itself recommends not to do it when KAlarm is already running. In such cases you should use the Dbus interface instead (explained here). The quick and dirty alternatives are:

  • in the script, precede the kalarm command with one that kills KAlarm, and follow it with one that restarts it in the background
  • write directly to the Kalarm calendar ($HOME/.kde/share/apps/kalarm/calendar.ics), that is:
    • open (just once) that file with a text editor
    • copy the snippet of text that describes one alarm (it starts with BEGIN:VEVENT and ends with END:VEVENT) in a text file, for example /tmp/MYEVENT.txt
    • write a script that:
    • replaces message, date and other parameters in MYEVENT.txt with those of your new alarm
    • prepends to the last line of the calendar file (the one saying END:VCALENDAR) the new value of MYEVENT.txt

Whatever mode you choose, driving KAlarm from a script will spare you the boring task of adding alarms manually, and also has two other advantages.

The first one is that you'll get automatic notifications, even from websites that don't announce events with iCalendar files or other machine-readable microformats. The other is not filling your mailbox with reminders only available by email: all you'd have to do is replace "download Web page or RSS feed" with "pass with procmail this email to the parsing script".

For more details, please check the command line operation section of the kalarm handbook. Of course, you can generalize this approach to any case in which you may need to generate alarms and/or calendar notifications from documents and events on yours or any other computer!