Documentation

USAGE: icalBuddy [options] <command>
<command> specifies the general action icalBuddy should take:
'eventsToday' Print events occurring today
'eventsToday+NUM' Print events occurring between today and NUM days into
the future
'eventsNow' Print events occurring at present time
'eventsFrom:START to:END'
Print events occurring between the two specified dates
'uncompletedTasks' Print uncompleted tasks
'undatedUncompletedTasks'
Print uncompleted tasks that have no due date
'tasksDueBefore:DATE'
Print uncompleted tasks that are due before the given
date, which can be 'today+NUM' or any regular date
'calendars' Print all calendars
'strEncodings' Print all the possible string encodings
'editConfig' Open the configuration file for editing in a GUI editor
'editConfigCLI' Open the configuration file for editing in a CLI editor
Some of the [options] you can use are:
-V Print version number (no <command> needed)
-u Check for updates to self online (no <command> needed)
-sc,-sd,-sp Separate by calendar, date or priority
-f Format output
-nc No calendar names
-nrd No relative dates
-npn No property names
-n Include only events from now on
-sed Show empty dates
-uid Show event/task UIDs
-eed Exclude end datetimes
-ea Exclude all-day events
-li Limit items (value required)
-std,-stda Sort tasks by due date (stda = ascending)
-tf,-df Set time or date format (value required)
-po Set property order (value required)
-ps Set property separators (value required)
-b Set bullet point (value required)
-ab Set alert bullet point (value required)
-ss Set section separator (value required)
-ic,-ec Include or exclude calendars (value required)
-iep,-eep Include or exclude event properties (value required)
-itp,-etp Include or exclude task properties (value required)
-cf,-lf Set config or localization file path (value required)
-nnr Set replacement for newlines within notes (value required)
See the icalBuddy man page for more info.
Version 1.8.8
Copyright 2008-2012 Ali Rantakari, http://hasseg.org/icalBuddy

Source code is available in a Git repository (click here to show/hide):

Changelog:

Older Versions:

Changelog:

Fixed the short name of the --maxNumNoteChars argument: it was in conflict with the short name of the --noCalendarNames option. --noCalendarNames's short name remains -nc and --maxNumNoteChars is now -nnc. Thanks to Steffen Nauhaus for noticing this.

Changelog:

When printing events in the Birthdays calendar, the age of the person will be printed as well. Note: if you are using a custom localization file, this requires that the localization string for someonesBirthday contains a placeholder for the age (e.g. %@'s birthday (age %i)). Learn more from the icalBuddyLocalization man page.

You can now print any part of an event or a task in the color of the calendar it belongs to. To do this, you would use calendar-color as a color value in the "formatting" section of the configuration file. Learn more from the icalBuddyConfig man page.

Added translations for task priority section titles for French and Spanish.

Changelog:

Changelog:

Added the -sp (or --separateByPriority) argument, which can be used to separate tasks by priority in the output.

When running icalBuddy calendars, the calendar colors are now used, which should make it easier to distinguish which calendar is which if some of them have the same name (particularily a problem with Exchange calendars).

Changelog:

Changelog:

Fixed mistake in documentation: the long form of the -npn argument is --noPropNames instead of --noPropertyNames.

Dropped support for PowerPC in the precompiled binaries (Apple's new dev tools (XCode 4) do not support PPC development anymore). You can still compile icalBuddy for PowerPC using older dev tools, though.

Changelog:

Calendars can now be included/excluded by type: the -ict (or --includeCalTypes) argument includes only items from calendars of the given types, and the -ect (or --excludeCalTypes) argument excludes items from calendars of the given types. The calendar types you can specify are CalDAV/iCloud, Exchange, IMAP, Local, Subscription, and Birthday. See the man page for more info on this feature.

Changelog:

Added the syntax specifiers for the -df and -tf (or --dateFormat and --timeFormat) argument values into the main man page because Apple's documentation for those has mysteriously disappeared from their web site.

Changelog:

Fixed bug where date sections were listed for each day that all multi-day-spanning events that occur during the specified date range spanned, even when these dates fell outside of the user-specified range. (Thanks to Karin H. for reporting this.)

Fixed bug where dates without a time (especially natural-language dates such as 'january 18, 2011') specified in the eventsFrom:DATE to:DATE command were considered with the time 12:00:00 by default (except if they were relative dates such as "tomorrow" or "today", in which case they were considered with the time 00:00:00). Now the times considered for dates specified without a time are 00:00:00 or 23:59:59 depending on whether the given date specifies the start or the end of a range, respectively.

Note 1: Scripts that use eventsFrom:to: without specifying times for the date ranges, and expect the times to be interpreted as 12:00 (noon), will have to be modified to explicitly specify the times.

Note 2: Scripts that use relative dates with shift amounts (like "tomorrow+1") for the eventsFrom:to: action might need to be modified, usually to remove one from the shift amount of the date specifying the end of the desired range — for example with this update you would use eventsFrom:tomorrow to:tomorrow to get events only for tomorrow (in previous versions the end date needed to be tomorrow+1, which is unintuitive).

Fixed bug where incorrect date ranges were listed when using the -sed (or --showEmptyDates) argument for printing tasks.

Changelog:

Changelog:

It's now possible to use some relative dates when using the eventsFrom:to: command argument (e.g.: icalBuddy eventsFrom:tomorrow to:"day after tomorrow").

It's now possible to specify a shift amount (i.e. number of days to add to or remove from) for relative dates (day before yesterday, yesterday, now, today, tomorrow or day after tomorrow) by adding +NUM or -NUM to the end (e.g. icalBuddy tasksDueBefore:yesterday-10).

Changelog:

Dates (for eventsFrom:DATE to:DATE and tasksDueBefore:DATE) can now be given in a more free format: for example "tomorrow at noon" or "june 10 at 6 pm".

The -d (or --debug) argument has been added; this will make icalBuddy print out some diagnostic information into the standard error stream (at the moment, it will print out info about how dates given in the input are interpreted).

Implemented custom date format specifier %RD which stands for "relative day" (or "date difference in days"): for example yesterday or 5 days from now. This (just like the "relative week" specifier %RW) can be used in the -df (or --dateFormat) argument values.

Changelog:

Added argument -uid (or --showUIDs) which will let you see the UIDs (unique identifiers) of events or tasks in your calendars.

The install.command script now allows for specifying a custom prefix for installation (example: install.command --prefix=~/opt) and it also automatically adjusts the default installation path to wherever icalBuddy seems to be installed already (for updating).

The uninstall.command script is able to search for the files to uninstall from nonstandard locations as long as the icalBuddy executable's parent directory is in the PATH environment variable.

Changelog:

Added output command tasksDueBefore:DATE which can be used to output only uncompleted tasks/todos that have a due date before the given DATE value (which can be given as today+NUM, tomorrow or "YYYY-MM-DD HH:MM:SS ±HHMM")

Changelog:

Calendar names are now colored using the calendar color in section titles as well (i.e. when using the -sc (or --separateByCalendar) argument) unless a section title foreground color has been specified in the configuration file's formatting section.

Changelog:

This is simply a new build of the latest version without a 64-bit Intel binary — some people that are running Leopard have been having icalBuddy hang on them and eat loads of memory and it seems this might be due to a bug in the 64-bit CalendarStore framework on Leopard (I don't have a Leopard machine to test on so thanks goes to Avery Chan for helping out with this). This update is a potential fix to those issues. If anyone for some reason wants a 64-bit icalBuddy, they can build it manually by executing the following command in the directory where they unzipped the release archive (before running the installation script): make 64BIT=1

Changelog:

Fixed a bug where when using the -sed (or --showEmptyDates) argument (and separating events by date), the date span to display sections for was interpreted as "span between the first and last found event" when the more logical solution is "span specified by user in the arguments" (which is how it works now).

Fixed a bug where the start time for a multi-day-spanning timed event was shown under all of the days it spans when separating events by date and excluding event end datetimes (now in these cases the start time is displayed as "..." under days on which the event does not start).

When printing events separated by date, the start and end times for a timed event that neither starts or ends on the date under which it's shown are now displayed as "... - ..." (instead of not at all).

Changelog:

Added the -sed (or --showEmptyDates) argument that display sections for empty dates (i.e. dates that have no items) that fall within the specified range as well. This argument applies only if the -sd (or --separateByDate) argument is used.

The tab (\t) escape sequence is now interpreted in some argument values.

Changelog:

If output formatting is turned on (via the -f or --formatOutput argument) and no foreground color is specified for event/task titles (in the config file's formatting section), the closest ANSI color to the color of the calendar will be used as the title foreground color.

Changelog:

Changelog:

Added the -std (or --sortTasksByDate) argument, which sorts tasks simply by their due dates (in descending order), as well as the -stda (or --sortTasksByDateAscending) argument, which does the same but in ascending order.

Fixed a bug where specifying the value "*" for either the -eep or the -etp arguments would exclude all properties instead of everything but the titles.

Changelog:

Changelog:

Added formatting keyword calendarNameInTitle which can be used to specify the formatting of the calendar names that are printed in parentheses next to event/task titles. (See the configuration file man page for more info on formatting keywords.)

Added localization keyword dateTimeSeparator which specifies what to print between the date and the time — in english, for example, " at " is used. (See the localization file man page for more info on localization keywords.)

Removed the -dts (or --dateTimeSeparator) argument due to the value it sets being specified in the localization file now.

Improved the formatting of the list of changes since the current version when running the automatic update (icalBuddy -u, followed by option a when you get the question of how to proceed.)

Added french localization file (by Matthieu Sieben — merci!)

Added PDF versions of all the three manual pages into the distribution package.

Changelog:

Added the -ps (or --propertySeparators) argument, which can be used to specify what to separate printed item properties with. The value for this argument is a string where each component is separated by an arbitrary character (which must also be present at the start and the end), like this: "|-first-|-second-|-third-|". The components in this list will be used as the separators between item properties in order from first (for the first printed property for an item) to last, using the last one several times if too few are specified. The default is "|\n |" (that's a newline followed by four spaces, used as the separator for all properties.) This argument can be used to print item properties on the same line (just specify a value that does not include a newline.)

Added an automatic update feature: run icalBuddy -u to check for updates and then if an update is found, respond to the question of how to proceed with option a, and icalBuddy will first display you a list of what's changed since the version you're running and then ask if you'd like it to automatically download the distribution package and update itself.

Added the -nnr (or --notesNewlineReplacement) argument, which can be used to specify the string to use for replacing newlines within values of the notes property.

Removed the -i (or --indent) argument (not needed anymore due to the new -ps argument, which provides similar behaviour in a more flexible way.)

Removed the -nni (or --notesNewlinesIndent) argument (not needed anymore due to the new -nnr argument, which provides similar behaviour in a more flexible way.)

Changelog:

Fixed bug where multi-day-spanning events were shown for each and every day they span, regardless of the specified date range to display, when using the -sd (or --separateByDate) argument. (as reported and tested by Kene and Micah -- thanks)

Added the -li (or --limitItems) argument which can be used to limit the number of printed items (events/tasks) to a maximum number.

Changelog:

Added the possibility to fully customize the formatting (colors, bolding, underlining) icalBuddy uses for the output (when the -f (or: --formatOutput) argument is used) via a per-user configuration file. See the icalBuddyConfig man page for documentation.

Added the possibility to set "constant" argument values via the per-user configuration file (that is, argument values that will always be true when you run icalBuddy, without having to always explicitly provide them as arguments to the executable.) See the icalBuddyConfig man page for documentation.

Added command arguments editConfig and editConfigCLI for automatically creating the configuration file if it doesn't exist and opening it in an editor (so for example you can run icalBuddy editConfig to open the configuration file in a GUI editor and icalBuddy editConfigCLI to open it in a command-line editor.)

Display the currently logged in user's birthday event from the Birthdays calendar by default as "My Birthday" (this is also localizable by using the key myBirthday.)

Fixed bug where parts of the output that were affected by command-line arguments were garbled if non-ASCII characters were passed in as the values for those arguments.

Made the default value of the section separator string "\n------------------------": the leading newline is now part of the section separator which means that it is now possible to either keep the section separator on the same line with the section title by specifying a value that doesn't have a newline in the beginning (e.g. icalBuddy -ss " -----") or just omit it completely by specifying an empty string (e.g. icalBuddy -ss "".)

Added argument -nni (or: --notesNewlinesIndent) for modifying the number of indenting whitespace characters to use when indenting additional lines in the "notes" property values. So for example if you're using icalBuddy with GeekTool and a non-fixed-width font, the indenting level for additional lines in the notes property values might be a bit off, so now you can use this argument to fix this (for example, run icalBuddy -nni 4 in order to add four whitespace characters to the indenting or icalBuddy -nni -2 to remove two.)

Made the "usage" output (i.e. what you see when you run icalBuddy without any arguments) a lot more succinct.

Changelog:

Implemented localization support: you can now create a property list file at ~/.icalBuddyLocalization.plist containing a dictionary mapping of localization keys (e.g. "someonesBirthday") to their human-readable equivalents (e.g. "%@'s Birthday"). Documentation for this feature can be found in the icalBuddyLocalization man page: just type man icalBuddyLocalization into the terminal. An example localization file for Finnish is included.

Changelog:

Fixed a bug where multi-day-spanning events were only displayed under the start day when separating by day (e.g. an event that spans from monday to tuesday would only be displayed under monday.)

Fixed a bug where sections would be displayed for the starting days of multi-day-spanning events (where the span would include the current date) when separating by day, even when the start date was before the current date (e.g. a section for "yesterday" would be shown with an event that spans from monday to tuesday if you ran icalBuddy -sd on tuesday.)

Fixed regression where past events for the current date were not shown when separating by day even though the -n argument was not set.

Changelog:

Fixed bug where the -i argument was not taken into account when indenting additional lines for values of the "notes" property (only exhibited if note values have line breaks.)

Fixed bug where having percentage characters (%) in any of the calendar items (i.e. in their titles or in any properties) made the output get garbled.

Added a lot more colors into the output (via ANSI escape sequences) if the -f argument is set.

Added more possible values for the "relative dates" (i.e. dates that are easily identifiable with a simple natural language phrase or word (in relation to the current date) instead of the standard representation specified by the date formatting string): in addition to "today" and "tomorrow", dates may now also be displayed as "day after tomorrow", "yesterday" or "day before yesterday".

Changelog:

Implemented custom date formatting specifier %RW, which stands for "relative week" (for example: last week, this week, next week, 2 weeks from now etc.) It can now be used in values for the date format (-df or --dateFormat) argument.

Added argument -b "value" (or --bullet "value") for specifying the string to use as the "bullet point" (the default is "* ".)

Added argument -ab "value" (or --alertBullet "value") for specifying the string to use as the "alert bullet point" (the default is "! ".)

Added argument -i "value" (or --indent "value") for specifying the string to use as the indentation for lines other than the first one for each item (i.e. the one that gets the bullet point) (the default is four spaces: " ".)

Added argument -ss "value" (or --sectionSeparator "value") for specifying the string to use as the "section separator" (i.e. the string that separates sections from items that belong to that section) (the default is "------------------------".)

Made installation a bit easier: the install script has been renamed to install.command so that you can run it directly from Finder by double-clicking. It will also tell you what it's going to do and prompt you to continue or cancel before actually starting to install.

Changelog:

Added shell script install.sh for installing the binary and the man page into the default locations so that users wouldn't need to have the OS X developer tools (i.e. make that's needed in order to run make install) installed. Update (feb 18, 2009): actually added the install.sh file into the package (it was missing before) :)

Changelog:

Added argument -sd (or --separateByDate) which will separate items in the output by their dates (start dates in the case of events and due dates in the case of tasks.)

Added argument -po (or --propertyOrder) which can be used to specify the order in which item (event or task) properties appear in the output. The allowed values (in the default order) are the following: title, location, notes, url, datetime, priority.

Changelog:

Changelog:

Made it possible to display events from farther on in the future by adding "+NUM" to the end of the "eventsToday" argument, where NUM is the number of days into the future you would like to see (i.e. "icalBuddy eventsToday+2" to also see events for tomorrow and the day after.)

Changed the -s (or --separate) argument to -sc (or --separateByCalendar) in order to allow for distinctions between different kinds of separation (like separation of items by date, which will be coming in a future update.)

Removed the -dtf (or --dateTimeFormat) argument as redundant (we can just use a combination of the date formatting string and the time formatting string to get a date-time formatting string.)

Added argument -dts (or --dateTimeSeparator) for specifying the separator string between dates and times in the output. The default is " at ".

Added some simple cases where dates would be formatted as natural language relative to the current date (e.g. "today" or "tomorrow" instead of "2009-02-05".)