icalpal
Description
icalpal is a command-line tool to query a macOS Calendar and Reminders databases for accounts, calendars, events, and tasks. It can be run on any system with Ruby and access to a Calendar or Reminders database.
Installation
As a system-wide Ruby gem:
gem install icalPal
or in your home diretory:
gem install --user-install icalPal
As a Homebrew formula:
brew tap ajrosen/icalpal
brew install icalpal
Features
Compatability with icalBuddy
icalpal tries to be compatible with icalBuddy for command-line options and for output. There are a some important differences to be aware of.
- Options require two hyphens, except for single-letter options that require one hyphen
- eventsFrom is not supported. Instead there is --from, --to, and --days
- uncompletedTasks is simply tasks
- undatedUncompletedTasks is simply undatedTasks
- tasksDueBefore:DATE is not yet supported
- The command can go anywhere; it doesn't have to be the last argument
- Property separators are comma-delimited
Additional commands
icalpal accounts
Shows a list of enabled Calendar accounts. Internally they are known as Stores; you can run icalpal stores
instead.
icalpal datedTasks
Shows only reminders that have a due date.
Additional options
- Options can be abbreviated, so long as they are unique. Eg.,
icalpal -c ev --da 3
is the same asicalpal -c events --days 3
. - The
-c
part is optional, but you cannot abbreviate the command if you leave it off. - Use
-o
to print the output in different formats. CSV or JSON are intertesting choices. - Copy your Calendar database file and use
--db
on it. -
--it
and--et
will filter by Calendar type. Types are Local, Exchange, CalDAV, MobileMe, Subscribed, and Birthdays -
--il
and-el
will filter by Reminder list -
--ia
includes only all-day events (opposite of--ea
) -
--aep
is like--iep
, but adds to the default property list instead of replacing it. -
--sep
to separate by any property, not just calendar (--sc
) or date (--sd
) -
--color
uses a wider color palette. Calendar colors are what you have chosen in the Calendar app. Not supported in all terminals, but looks great in iTerm2. -
--match
lets you filter the results of any command to items where a FIELD matches a regular expression. Eg.,--match notes=zoom.us
to show only Zoom meeetings
Because icalpal is written in Ruby, and not a native Mac application, you can run it just about anywhere. It's been tested with the version of Ruby (2.6.10) included with macOS.
Usage
icalpal: Usage: icalpal [options] [-c] COMMAND
COMMAND must be one of the following:
events Print events
tasks Print tasks
calendars Print calendars
accounts Print accounts
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
datedTasks Print tasks with a due date
undatedTasks Print tasks with no due date
Global options:
-c, --cmd=COMMAND Command to run
--db=DB Use DB file instead of Calendar (default: /Users/ajr/Library/Calendars/Calendar.sqlitedb)
For the tasks commands this should be a directory containing .sqlite files
(default: /Users/ajr/Library/Group Containers/group.com.apple.reminders/Container_v1/Stores)
--cf=FILE Set config file path (default: /Users/ajr/.icalpal)
-o, --output=FORMAT Print as FORMAT (default: default)
[ansi, csv, default, hash, html, json, md, rdoc, remind, toc, xml, yaml]
Including/excluding calendars and reminders:
--is=ACCOUNTS List of accounts to include
--es=ACCOUNTS List of accounts to exclude
--it=TYPES List of calendar types to include
--et=TYPES List of calendar types to exclude
[Local, Exchange, CalDAV, MobileMe, Subscribed, Birthdays]
--ic=CALENDARS List of calendars to include
--ec=CALENDARS List of calendars to exclude
--il=LISTS List of reminder lists to include
--el=LISTS List of reminder lists to exclude
--match=FIELD=REGEXP
Include only items whose FIELD matches REGEXP (ignoring case)
Choosing dates:
--from=DATE List events starting on or after DATE
--to=DATE List events starting on or before DATE
DATE can be yesterday, today, tomorrow, +N, -N, or anything accepted by DateTime.parse()
See https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse
-n Include only events from now on
--days=N Show N days of events, including start date
--sed Show empty dates with --sd
--ia Include only all-day events
--ea Exclude all-day events
Choose properties to include in the output:
--iep=PROPERTIES List of properties to include
--eep=PROPERTIES List of properties to exclude
--aep=PROPERTIES List of properties to include in addition to the default list
--itp=PROPERTIES List of task properties to include
--etp=PROPERTIES List of task properties to exclude
--atp=PROPERTIES List of task properties to include in addition to the default list
Included for backwards compatability, these are aliases for --iep, --eep, and --aep
--uid Show event UIDs
--eed Exclude end datetimes
--nc No calendar names
--npn No property names
--nrd No relative dates
Properties are listed in the order specified
Use 'all' for PROPERTIES to include all available properties (except any listed in --eep)
Use 'list' for PROPERTIES to list all available properties and exit
Formatting the output:
--li=N Show at most N items (default: 0 for no limit)
--sc Separate by calendar
--sd Separate by date
--sp Separate by priority
--sep=PROPERTY Separate by PROPERTY
--sort=PROPERTY Sort by PROPERTY
--std Sort tasks by due date (same as --sort=due_date)
--stda Sort tasks by due date (ascending) (same as --sort=due_date -r)
-r, --reverse Sort in reverse
--ps=SEPARATORS List of property separators
--ss=SEPARATOR Set section separator
--df=FORMAT Set date format
--tf=FORMAT Set time format
See https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-i-strftime for details
-b, --bullet=STRING Use STRING for bullets
--ab=STRING Use STRING for alert bullets
--nb Do not use bullets
--nnr=SEPARATOR Set replacement for newlines within notes
-f Format output using standard ANSI colors
--color Format output using a larger color palette
Help:
-h, --help Show this message
-V, -v, --version Show version and exit (2.0.0)
-d, --debug=LEVEL Set the logging level (default: warn)
[debug, info, warn, error, fatal]
Environment variables:
ICALPAL Additional arguments
ICALPAL_CONFIG Additional arguments from a file
(default: /Users/ajr/.icalpal)
Output formats
icalpal supports several output formats. The default format tries to mimic icalBuddy as much as possible.
CSV, Hash, JSON, XML, and YAML print all fields for all items in their respective formats. From that you can analyze the results any way you like.
Remind format uses a minimal implementation built in icalpal.
Other formats such as ANSI, HTML, Markdown, RDoc, and TOC, use Ruby's RDoc::Markup framework to build and render the items.
Each item to be printed is a new RDoc::Markup::Document.
When using one of the separate by options, a section header is added first. The section contains:
- RDoc::Markup::BlankLine (unless this is the first section)
- RDoc::Markup::Heading (level 1)
- RDoc::Markup::Rule
The rest of the document is a series of RDoc::Markup::List objects, one for each of the item's properties:
- RDoc::Markup::List
- RDoc::Markup::Heading (level 2)
- RDoc::Markup::BlankLine
- RDoc::Markup::ListItem
- RDoc::Markup::Paragraph
The document will also include a number of RDoc::Markup::Verbatim and RDoc::Markup::Raw items. They are not included in the output, but are used to pass information about the item and property to the default formatter.
History
I used icalBuddy for many years. It's great for scripting, automation, and as a desktop widget for apps like GeekTool and Übersicht.
As with many applications, I started to run into some limitations in icalBuddy. The biggest being that active development ended in 2014. It's only thanks to the efforts of Jim Lawton that it even compiles anymore.
Instead of trying to understand and extend the existing code, I chose to start anew using my language of choice: Ruby. Using Ruby meant there is much less code; about 1,600 lines vs. 7,000. It also means icalpal is multi-platform.
I won't pretend to understand why you would want to run this on Linux or Windows. But since icalpal is written in Ruby and gets its data directly from the Calendar and Reminders database files instead of an API, you can.