icalBuddy Usage Examples

I've noticed that a lot of people who are not familiar with the command line have been using icalBuddy with GeekTool in order to display events and tasks from their calendars on their desktops. I understand how dealing with the user interface of a command-line application (i.e. figuring out arcane combinations of weird command arguments) might be daunting so I thought I'd make this page to try and help out by showing some examples of what kind of output you can get from icalBuddy (and what arguments you need to use to get them).

Even if you're a regular Unix Hacker™ this might still give you a good understanding of what this program is good for.

Basic Examples: Events

Events Today

First we'll simply use the eventsToday command argument to print out all the events occurring today.

/usr/local/bin/icalBuddy eventsToday

• Walk goldfish (Home) location: Around the house 08:00 - 09:00 • Dinner with boss (Home) location: Chez Dominique 21:00 - 23:59

This is what the default output looks like.

(Note that the date and time formats are taken from System Preferences by default, so they might look different on your computer.)

Events Later Today

In the previous example the output shows all events for the current date, including past ones. We can exclude events that have already passed simply by adding the -n (or --includeOnlyEventsFromNowOn) argument:

/usr/local/bin/icalBuddy -n eventsToday

• Dinner with boss (Home) location: Chez Dominique 21:00 - 23:59

So now we only get events occurring later today. You can use the -n argument whenever you want to exclude past events from the output.

Events in the Near Future

Let's use the same command as in the first example, but add +10 after eventsToday:

/usr/local/bin/icalBuddy eventsToday+10

• Walk goldfish (Home) location: Around the house today at 08:00 - 09:00 • Dinner with boss (Home) location: Chez Dominique today at 21:00 - 23:59 • Synergy Meeting (Work) location: Meeting Room C, Building A notes: Bring snacks url: http://google.com/?q=synergy tomorrow at 13:00 - 16:00 • Jane Doe's Birthday (Birthdays) day after tomorrow • Fill weekly timesheet (Work) 16.07.2010 at 15:00 - 16:00 • Eddie DoobleDoo's Birthday (Birthdays) 17.07.2010 • Synergy Conference (Work) location: London 19.07.2010 - 21.07.2010 • Initech booth open (Work) location: Building B, main hall 19.07.2010 at 08:00 - 21.07.2010 at 12:00 • Lunch with Benny (Home) location: Hesburger 22.07.2010 at 12:00 - 13:00

We get a bit more stuff now. The eventsToday+10 command argument gives us events occurring today and 10 days into the future. You can of course do this with any number, like eventsToday+1 to get events for today and tomorrow, for example.

Events in the Near Future — In TechniColor™

Now let's add the -f (or --formatOutput) argument:

/usr/local/bin/icalBuddy -f eventsToday+10

Whee! That looks a lot nicer. In fact, I like colors so much that I'm just going to keep this argument in all my commands from now on.

(Note that icalBuddy tries to choose colors that match the calendar colors set in iCal as closely as possible for the item titles, but these colors won't match exactly because command-line programs can only use 16 colors via ANSI escape sequences. Depending on the program you're using to display icalBuddy's output, you might be able to tune each of these colors to your liking (NerdTool can do this, for example) but the fact that there'll only ever be 16 of them remains.)

Events in the Near Future, Separated by Date

In the previous examples all of the events are in the same continuous list. We can separate them by date by adding the -sd (or --separateByDate) argument:

/usr/local/bin/icalBuddy -f -sd eventsToday+10

today: ------------------------ • Walk goldfish (Home) location: Around the house 08:00 - 09:00 • Dinner with boss (Home) location: Chez Dominique 21:00 - 23:59 tomorrow: ------------------------ • Synergy Meeting (Work) location: Meeting Room C, Building A notes: Bring snacks url: http://google.com/?q=synergy 13:00 - 16:00 day after tomorrow: ------------------------ • Jane Doe's Birthday (Birthdays) 16.07.2010: ------------------------ • Fill weekly timesheet (Work) 15:00 - 16:00 17.07.2010: ------------------------ • Eddie DoobleDoo's Birthday (Birthdays) 19.07.2010: ------------------------ • Synergy Conference (Work) location: London • Initech booth open (Work) location: Building B, main hall 08:00 - ... 20.07.2010: ------------------------ • Synergy Conference (Work) location: London • Initech booth open (Work) location: Building B, main hall ... - ... 21.07.2010: ------------------------ • Synergy Conference (Work) location: London • Initech booth open (Work) location: Building B, main hall ... - 12:00 22.07.2010: ------------------------ • Lunch with Benny (Home) location: Hesburger 12:00 - 13:00

Notice that these are the same events as in the previous example, they're just separated under date headings.

Events in the Near Future, Separated by Calendar

Instead of separating events by date, we can separate them by calendar with the -sc (or --separateByCalendar) argument:

/usr/local/bin/icalBuddy -f -sc eventsToday+10

Home: ------------------------ • Walk goldfish location: Around the house today at 08:00 - 09:00 • Dinner with boss location: Chez Dominique today at 21:00 - 23:59 • Lunch with Benny location: Hesburger 22.07.2010 at 12:00 - 13:00 Work: ------------------------ • Synergy Meeting location: Meeting Room C, Building A notes: Bring snacks url: http://google.com/?q=synergy tomorrow at 13:00 - 16:00 • Fill weekly timesheet 16.07.2010 at 15:00 - 16:00 • Synergy Conference location: London 19.07.2010 - 21.07.2010 • Initech booth open location: Building B, main hall 19.07.2010 at 08:00 - 21.07.2010 at 12:00 Birthdays: ------------------------ • Jane Doe's Birthday day after tomorrow • Eddie DoobleDoo's Birthday 17.07.2010

Again — same events as before, just under calendar headings this time.

Events Within an Arbitrary Date Span

We can use the eventsFrom:DATE to:DATE command argument to ask for events between any two date/times:

/usr/local/bin/icalBuddy -f eventsFrom:'july 20, 2010' to:'july 22, 2010 at 9pm'

• Synergy Conference (Work) location: London 19.07.2010 - 21.07.2010 • Initech booth open (Work) location: Building B, main hall 19.07.2010 at 08:00 - 21.07.2010 at 12:00 • Lunch with Benny (Home) location: Hesburger 22.07.2010 at 12:00 - 13:00

You can specify the date values pretty freely here — last tuesday, tomorrow at noon or jul 3 at 5am are all acceptable, for example.

(Pro tip: if you want to make sure that icalBuddy has interpreted your date inputs correctly, add the -d (or --debug) argument and it'll tell you.)

Basic Examples: Tasks

Uncompleted Tasks

We can switch the command argument to uncompletedTasks:

/usr/local/bin/icalBuddy -f uncompletedTasks

! Buy a Sony Walkman (Home) notes: Everybody else has one! due: 13.06.1987 priority: high • Synergize Workflows (Work) due: 16.07.2010 priority: medium • Feed the snow leopard (Home) due: day after tomorrow

This will give us all uncompleted tasks, sorted by priority.

You can sort tasks by their due date by adding either the -std (or --sortTasksByDate) or the -stda (or --sortTasksByDateAscending) argument (sort in descending or ascending order, respectively).

(Notice those red exclamation marks? Those are "alert bullet points" and they are used in place of the standard bullet point for tasks that are past their due date. You can change both the regular and the alert bullet points to whatever you want.)

Uncompleted Tasks Due in the Near Future

If we're only interested in seeing uncompleted tasks that are due soon (let's say within the next three days) we can use the tasksDueBefore:DATE command argument with today+3 as the date:

/usr/local/bin/icalBuddy -f tasksDueBefore:today+3

! Buy a Sony Walkman (Home) notes: Everybody else has one! due: 13.06.1987 priority: high • Feed the snow leopard (Home) due: day after tomorrow

You can specify any date (like tomorrow, 'aug 10', 'next sunday' or '2010-10-03 22:00:00 +02:00') for tasksDueBefore: but using today+NUM is useful for always getting the near future tasks regardless of what the current date is.

Uncompleted Tasks Due in the Near Future, Separated by Calendar

We can add the -sc (or --separateByCalendar) argument here as well:

/usr/local/bin/icalBuddy -f -sc tasksDueBefore:today+7

Home: ------------------------ ! Buy a Sony Walkman notes: Everybody else has one! due: 13.06.1987 priority: high • Feed the snow leopard due: day after tomorrow Work: ------------------------ • Synergize Workflows due: 16.07.2010 priority: medium

Both events and tasks can be separated by calendar (as seen here) as well as by (due) date (with the -sd (or --separateByDate) argument).

More Advanced Examples

Getting Started With Custom Output Formatting

In order to make changes to the output formatting you need to edit the icalBuddy configuration file. I suggest you install the OS X developer tools (XCode etc.) before doing that because the Property List Editor application, which is strongly suggested for editing the configuration file, will then be available on your computer. The developer tools can be installed from the system discs that came with your Mac or downloaded from Apple's website.

In order to open the icalBuddy configuration file for editing, simply run the following command in the Terminal:

/usr/local/bin/icalBuddy editConfig

If you have the Developer Tools (XCode etc.) installed, this will open the config file in Property List Editor. Then you can just start adding key-value pairs under the formatting section (remember to save the file when you're done, though).

Config file example image

You can check out the examples below as well as the configuration file man page for more info.

Underlined Section Titles

You can make section titles more concise by making them underlined while removing the section separators completely:

/usr/local/bin/icalBuddy -f -sc -ss "" eventsToday+10

Home: • Walk goldfish location: Around the house today at 08:00 - 09:00 • Dinner with boss location: Chez Dominique today at 21:00 - 23:59 • Lunch with Benny location: Hesburger 22.07.2010 at 12:00 - 13:00 Work: • Synergy Meeting location: Meeting Room C, Building A notes: Bring snacks url: http://google.com/?q=synergy tomorrow at 13:00 - 16:00 • Fill weekly timesheet 16.07.2010 at 15:00 - 16:00 • Synergy Conference location: London 19.07.2010 - 21.07.2010 • Initech booth open location: Building B, main hall 19.07.2010 at 08:00 - 21.07.2010 at 12:00 Birthdays: • Jane Doe's Birthday day after tomorrow • Eddie DoobleDoo's Birthday 17.07.2010

Values for config file formatting section
sectionTitle	bold, underlined

The section separators (i.e. the dashes: ---------) can be removed by specifying an empty value for the -ss (or --sectionSeparator) argument.

The section title can be made underlined by adding the value underlined for the sectionTitle formatting key in the config file's formatting section.

Custom Bullet Points

You can customize both the regular and the "alert" bullet points to your liking:

/usr/local/bin/icalBuddy -f -b ">> " -ab "!! " -ps "|\n     |" uncompletedTasks

!! Buy a Sony Walkman (Home) notes: Everybody else has one! due: 13.06.1987 priority: high >> Synergize Workflows (Work) due: 16.07.2010 priority: medium >> Feed the snow leopard (Home) due: day after tomorrow

Values for config file formatting section
alertBullet	bold, white, bg:red
bullet	white, bg:blue

You can specify your own bullet points with the -b (or --bullet) argument, as well as your own alert bullet points with the -ab (or --alertBullet) argument.

You can customize the bullet point formatting by specifying whatever formatting parameters you'd like (e.g. bold,red) for the bullet and alertBullet keys in the config file's formatting section.

In order to indent the property lines one character further, we'll replace the default value for the -ps (or --propertySeparators) argument (a newline followed by four spaces) with a newline followed by five spaces.

Very Concise Event/Task List

We can get a very concise listing of events or tasks (this example shows events but the same arguments work for tasks as well) with just a few arguments:

/usr/local/bin/icalBuddy -f -npn -nc -ps "/ » /" -eep "url" eventsToday+10

• Walk goldfish » Around the house » today at 08:00 - 09:00 • Dinner with boss » Chez Dominique » today at 21:00 - 23:59 • Synergy Meeting » Meeting Room C, Building A » Bring snacks » tomorrow at 13:00 - 16:00 • Jane Doe's Birthday » day after tomorrow • Fill weekly timesheet » 16.07.2010 at 15:00 - 16:00 • Eddie DoobleDoo's Birthday » 17.07.2010 • Synergy Conference » London » 19.07.2010 - 21.07.2010 • Initech booth open » Building B, main hall » 19.07.2010 at 08:00 - 21.07.2010 at 12:00 • Lunch with Benny » Hesburger » 22.07.2010 at 12:00 - 13:00

We use the -npn (or --noPropertyNames) argument to omit all property names and the -nc (or --noCalendarNames) argument to omit all calendar names.

Specific properties can be excluded by using the -eep (or --excludeEventProperties) and -etp (or --excludeTaskProperties) arguments. Here we exclude the URL properties.

In order to keep all properties (location, notes, date/time etc.) of the same events/tasks on the same line we set the value "/ » /" for the -ps (or --propertySeparators) argument. This means that icalBuddy should separate all properties with the string » (the slashes at the beginning and the end are just the separator characters — see the man page for more info).

Even More Concise Event/Task List

If we only want to see the titles of events/tasks — and nothing else — that's possible too:

/usr/local/bin/icalBuddy -f -npn -nc -eep "*" eventsToday+10

• Walk goldfish • Dinner with boss • Synergy Meeting • Jane Doe's Birthday • Fill weekly timesheet • Eddie DoobleDoo's Birthday • Synergy Conference • Initech booth open • Lunch with Benny

We use the same arguments here as in the last example except we now give "*" as the value for the -eep argument in order to exclude all properties.

Even More Concise Event/Task List With Relative Dates

We can add relative dates with one-day precision to the previous example like this:

/usr/local/bin/icalBuddy -f -npn -nc -iep "title,datetime" -ps "| : |" -po "datetime,title" -tf "" -df "%RD" -eed eventsToday+10

• today : Walk goldfish • today : Dinner with boss • tomorrow : Synergy Meeting • day after tomorrow : Jane Doe's Birthday • 4 days from now : Fill weekly timesheet • 5 days from now : Eddie DoobleDoo's Birthday • 7 days from now : Synergy Conference • 7 days from now : Initech booth open • 10 days from now : Lunch with Benny

We use the -iep (or --includeEventProperties) argument to include only event titles and date/times from all the properties and the -po (or --propertyOrder) argument to order the date/times first and the titles second.

We only want to see the start dates of events here so we add the -eed (or --excludeEndDates) argument. We set an empty value for the -tf (or --timeFormat) argument to keep times from showing and "%RD" as the value for the -df (or --dateFormat) argument in order to print dates in simple day-precision relative terms.

We also set "| : |" as the -ps (or --propertySeparators) argument value to separate the two properties by :.

Further Information

That's it for the examples — be sure to check out the man page for a complete list of all the arguments you can use to customize your output.

If you want to customize the colors used or set constant arguments you can do that by creating and editing the configuration file. See the configuration file man page for more info.

The Frequently Asked Questions document will probably be useful as well.

Table of Contents