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.
Table of Contents
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
• 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
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).
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.