Cron Calendar Date and Time Trigger

Version 8 adds the new Cron trigger, which lets you trigger macros periodically based on calendar dates and times.

Cron (Wikipedia) is a unix system that lets you schedule tasks to be run periodically in very flexible ways, and so kKeyboard Maestro8 adopts this technique to let you trigger macros.

A cron entry looks like this:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │ ┌───────────── optional year of week
│ │ │ │ │ │
* * * * * *

Each field can be a single number, or it can be a range (eg “3-7”) or a set of numbers or ranges separated by commas (eg “3,5-7,9”). Alternatively, the field can be * which matches all values. You can also add / and a number after a range to match every N'th value (eg “0-25/5” will match every five minutes in the first half of the each hour).

For the Day of Week and Month fields, you can use the first three letters of the English name (eg “Jan” for January (1), or “Sun” for Sunday (0)).

If the field starts with a minus sign (-), it matches from the end of the range (eg -1 in day of the month means the last day of the month).

The trigger will match when all fields match the current time (as each minute ticks over). Exception: if either day of month or day of week is * and the other isn't, then the trigger will match only the non-* field, otherwise the trigger will match when either field matches.

If you start the day of the week field with a +, then the trigger will match only if both the day of the week and day of the month field matches. This allows you to match the last Friday of the month using “-1-7” for the day of the month, and “+Fri” for the day of the week.

Alternatively, you can use tags like @yearly or @daily, but that is more for compatibility than generally useful.

Remember that your Mac must be awake for any trigger to run, and that if the screen is sleeping, locked, or screen saving, then UI actions generally will not work.

So for example, you can trigger a macro at the start of each Monday with 0 8 * * Mon.

By combining the day and day of week fields, you can trigger on the first, second, or last or second last Monday of each month, and endless more possibilities.

See the wiki page for more examples.


This thing is really useful too for this.

1 Like

Hey Peter, I’m trying to write cron for first Saturday of each of month at 8:30am? Is that possible? What I got is 30 8 * * Sat, but I’m not sure if that gets me the first Saturday of the month. It’s says in KM that it’s on Sat in every month. Does that mean first Sat?

That would be every Saturday. You want:

30 8 1-7 * +Sat

Awe, okay, thanks, appreciate it. I saw the 1-7 in the document, but I didn’t quite understand it.

@Bakari45 and @peternlewis,

I added this example to the Cron Trigger Examples -- KM Wiki.