icalBuddy

To use icalBuddy in a language other than English, copy one of the included example localization files to ~/.icalBuddyLocalization.plist.

cp [example_localization_file] ~/.icalBuddyLocalization.plist

To customize output formatting (like colors or bullet points), you must edit the configuration file. You can open the editor directly from the terminal using the editConfig command.

Note: It is recommended to have OS X developer tools (XCode) installed so the Property List Editor can be used to edit the file.

/usr/local/bin/icalBuddy editConfig

By default, icalBuddy installs to /usr/local. To install to a different prefix (e.g., your home folder):

1. Run install.command.
2. Choose the c option ("change installation path").
3. Enter your desired prefix (e.g., ~/local).

With a prefix of ~/local, the executable will be at ~/local/bin/icalBuddy and manual pages at ~/local/share/man/man1.

Important: If you use a custom location, you must add the new paths to your PATH and MANPATH environment variables in your shell configuration file (e.g., ~/.bashrc or ~/.zshrc):

export PATH=${PATH}:/Users/username/local/bin
export MANPATH=${MANPATH}:/Users/username/local/share/man

To install icalBuddy on macOS, locate the install.command file in the distribution and double-click it in Finder. This will launch a Terminal script that displays the intended installation locations and prompts you to confirm the installation.

Double-click `install.command` in Finder

The icalBuddy distribution archive includes scripts for installation and uninstallation. You can run install.command to install or uninstall.command to remove the application by double-clicking them in Finder or executing them via the Terminal.

# Run via terminal
./install.command
./uninstall.command

If you have multiple calendars with the same name (common with Exchange), use the -ic (--includeCals) or -ec (--excludeCals) arguments with the calendar's unique identifier (UID) instead of the name.

To find the UIDs for your calendars, run: icalBuddy calendars.

# List calendars to find UIDs
$ icalBuddy calendars

# Example output showing UID
• Calendar
  type: Exchange
  UID: 3F0B97F7-0B88-48E3-BDAB-977382767D28

# Use the UID to include a specific calendar
icalBuddy -ic 3F0B97F7-0B88-48E3-BDAB-977382767D28

icalBuddy provides several ways to learn how to use the utility and configure it:

• Command-line arguments: Run man icalBuddy in the terminal to view the manual page containing all available arguments.
• Configuration file: Run man icalBuddyConfig in the terminal to learn about the configuration file format and how to customize icalBuddy's behavior.
• Localization: Run man icalBuddyLocalization in the terminal to learn how to write your own localizations.
• FAQ: Open the faq.html file in a web browser for additional guidance.
• PDF versions: Manual pages are also available as PDF files within the distribution.

As of version 1.7.13, you can specify relative dates in arguments to fetch events relative to the current date.

Supported relative dates:

• day before yesterday
• yesterday
• today
• now
• tomorrow
• day after tomorrow

You can apply a 'day shift' by appending +NUM or -NUM to these keywords (e.g., tomorrow+1 for the day after tomorrow).

For high-precision requirements, use the format YYYY-MM-DD HH:MM:SS ±HHMM.

# Get events for tomorrow
icalBuddy eventsFrom:tomorrow to:tomorrow

# Get events for tomorrow and the day after tomorrow
icalBuddy eventsFrom:tomorrow to:'day after tomorrow'

To use a custom language, copy a localization file from the exampleLocalizationFiles directory in the distribution archive to your home folder and name it .icalBuddyLocalization.plist.

Example: Setting up French localization

cp exampleLocalizationFiles/french-icalBuddyLocalization.plist ~/.icalBuddyLocalization.plist

If you see an error stating Address book access is denied for executable at path..., it means icalBuddy lacks permission to access your contacts.

Option 1: Grant Permission Go to System Preferences > Security & Privacy > Privacy, select Contacts, and check the box next to icalBuddy.

Option 2: Suppress Errors If you do not want to grant access, redirect stderr to /dev/null in your command:

/usr/local/bin/icalBuddy -sd eventsToday+10 2>/dev/null

If icalBuddy is not found, it is likely not in your PATH.

For standard shells: Add the installation directory (default /usr/local/bin) to your PATH in your shell config file: export PATH=$PATH:/usr/local/bin

For GeekTool: GeekTool does not load shell configuration files. You must either:

1. Use the absolute path to the executable: /usr/local/bin/icalBuddy <arguments>
2. Explicitly source your shell configuration in the command: source ~/.bashrc; icalBuddy <arguments>