icalBuddy: Getting Events and Tasks from the OS X Calendar Store via the Command Line

Filed under Mac, Programming

icalBuddy example pic I'm a big fan of the "do not repeat yourself" principle, which, especially in the context of software, basically means that you should only have one place to change anything. Any highly volatile data that will be viewed from more than one location (or in more than one way) should only have one location and/or interface for changing it. This way, whenever someone, somewhere, at some point in time happens to make changes to that data, all of the views that display it will reflect that change in true automated synchronization with my cell phone to work.

I used dashboard widgets for a while for getting a quick overview of all of the events I have planned for the day plus any uncompleted tasks I might have, but soon noticed that I don't actually go and see what's up in the dashboard very often, which lead to me forgetting some things even though I had them set up as events or tasks in my calendars. The perfect place for displaying events for the day and any uncompleted tasks for me would thus be the desktop, which, even though it is most of the time obscured by a bunch of windows, I'll occasionally glance at during the day. GeekTool is the solution for displaying any textual output from the shell on an OS X desktop, and I was using that already for some other things, so all that I needed was a CLI application or script that would get the events and tasks from the calendar store and output them in a nice readable way.

The only solution for this that I could find was made by some people over at macosxhints.com, who had come up with a Perl script for this purpose, but it didn't seem very generic or reliable, so I started implementing my own version. I first tried to do it in Python, but soon ran into complexity issues with recurring events. Also, it wasn't very fast. This was basically when I slapped myself in the head and realized that Apple has already provided a very nice API in Objective-C for getting calendar items from the database and working with them. With this, I started over and managed to come up with icalBuddy. Here's an example of what its output might look like (this is a list of uncompleted tasks, separated by calendar:)

$ icalBuddy -sc uncompletedTasks
Blog stuff:
* Write blog post about icalBuddy
    notes: add some nice pictures
    priority: high

* Bask in your awesomeness
    priority: medium
* Try not to be so great all the time
    notes: People are getting jealous
    url: http://hasseg.org

Here's what it looks like on my desktop via GeekTool:

I have a separate page up on this site for the application itself, including download links, examples of use and documentation (read: HTML version of the man page,) so head on over there if you're interested.


Robbie January 30, 2009 at 9:22 PM

Thanks for the great script, been after something for this for a while now. How did you set up your geektool entry for icalBuddy? I’ve tried the geektool shell setting and added: icalBuddy eventsToday but I got no output. Regards, Robbie

Ali Rantakari February 1, 2009 at 12:08 AM

Hi Robbie,

Either make sure that the location of the icalBuddy binary is added to your PATH environment variable in your shell config file (~/.bashrc or ~/.bash_profile) or just use an absolute path in the geektool entry (/usr/local/bin/icalBuddy or wherever it is that you have it)

Matt February 2, 2009 at 6:22 PM

Wow! I’ve been looking around the various ways of printing events and todos to GeekTool, and this is the best I’ve seen by far. Thanks a lot.

Gerry March 12, 2009 at 12:32 AM

Thanks a lot for this. It makes for a great companion for GeekTool.


Ansis March 23, 2009 at 5:14 PM

Thanks, this is great script - to have a list of calendars on the desktop. Just one thing - I can not find how to get UTF 8 encoding to work?

Ali Rantakari March 23, 2009 at 6:18 PM

Hi Ansis,

Check out the FAQ for info on how to enable UTF-8 in Apple’s Terminal.app, iTerm and GeekTool.

Ansis March 23, 2009 at 7:13 PM

Thanks, Ali! GeekTool with UTF-8 support worked just fine! Thanks again - now I have also localized latvian version!

Uday April 10, 2009 at 9:54 PM

Discovered GeekTool couple of weeks ago and this utility absolutely complements it. Makes GeekTool look good honestly.

Thanks for the great work!

meldon April 19, 2009 at 4:58 PM

Hi, I am not familiar with ANSI escape code, and wish to change the way the information taken from iCal is displayed. Can you help me?

Ali Rantakari April 19, 2009 at 9:50 PM

Hi Meldon,

You just need to use a program that supports ANSI escape sequences to call icalBuddy and display its output. Apple’s Terminal.app and iTerm both support them, but GeekTool doesn’t.

I’ve actually added support for ANSI escape sequences (as well as a couple of other things) into GeekTool but I’ve had some trouble contacting the original author about licensing issues (I’m not comfortable releasing my version of it to the general public if no open-source license is specified for the original code.) I hope I get this sorted out with him ASAP, since I’d love to release my changes to it.

Ali Rantakari July 12, 2009 at 3:00 AM

I’ve just released my custom build of GeekTool 2 with support for ANSI escape sequences:


Jude November 22, 2009 at 8:22 PM

THANKYOU THANKYOU! I have been trying to automate my calendar through applescript and it has turned into a major pain. This helps a lot!

Matt Brown February 19, 2010 at 7:23 AM

I had success utilizing the iCalBuddy Output with GeekTool. THanks for the great writeup!

However, I’m having trouble with my output. For some reason, each of my event titles is preceded by â¢, or â¢

How can i correct this? Any idea where this is coming from?


Anthony April 13, 2010 at 7:41 AM

Running this on an 10.5 Core 2 Duo yields bad results. I can get the list of calendars, but asking for simple things like eventsToday causes the application to spin, eating as much memory as it can get. I’ve let it run for a minute or two, consuming ~2GB RAM, and then killed it without getting any output.

Anyone seen this? Any idea what’s up?

Ali Rantakari April 13, 2010 at 11:23 AM

Hi Anthony,

I’ve heard from a couple of users about the problem you describe. I sent debug binaries to one user who then forwarded the log outputs to me and I traced the hangup to the call that goes out to the OS CalendarStore framework to retrieve the calendar items. The predicate object used in the call seemed fine as well so it looked like there might be a bug in the Leopard CalendarStore, especially since I haven’t heard of anyone having this issue on Snow Leopard.

I can’t really do any proper testing related to this since I don’t have Leopard installed at home anymore; our Mac Mini (which I had running Leopard for testing purposes) started having display issues a while back so I had to upgrade it to Snow Leopard.

Anthony April 13, 2010 at 4:43 PM

Okay. I’ve got Snow Leopard and have been putting off the upgrade for an unrelated reason. I’ll give this a shot again once I’ve done it. Thanks for the response.

Ali Rantakari April 13, 2010 at 11:07 PM


If you could let me know at some point if upgrading to 10.6 seems to fix the issue, that would be great. I would then feel more comfortable adding an entry into the FAQ about this.

Ali Rantakari April 28, 2010 at 11:59 AM


I released a new version of icalBuddy that might fix the hangups you’ve been encountering – you should give it a try. You can update it by running “icalBuddy -u” in the terminal or by downloading it from the website and installing it manually.

Anthony April 28, 2010 at 8:18 PM

i did a manual install and it works great! this is awesome; much thanks.

Nate May 18, 2010 at 4:07 PM

Very nice tool–exactly what I was looking for a home-brewed controller for a network thermostat.

Any idea how to get icalBuddy to display “Delegate” calendars (i.e. calendar accounts like gmail, etc. setup in iCal proper)?

Ali Rantakari May 18, 2010 at 4:09 PM

Nate: Check out the second-to-last question in the FAQ.

Nate May 18, 2010 at 4:18 PM

I see, thanks! If only I could read…

Zettt May 20, 2010 at 11:18 AM

Thanks for this program! I love it. Much appreciated.

Rhywun May 23, 2010 at 1:32 AM

Great stuff! I’ve been trying to do this too with AppleScript with no luck. Thanks!