Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ajrosen/icalPal
Command-line tool to query the macOS Calendar and Reminders
https://github.com/ajrosen/icalPal
calendar macos reminders
Last synced: about 2 months ago
JSON representation
Command-line tool to query the macOS Calendar and Reminders
- Host: GitHub
- URL: https://github.com/ajrosen/icalPal
- Owner: ajrosen
- License: gpl-3.0
- Created: 2023-02-17T19:41:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-15T00:51:15.000Z (4 months ago)
- Last Synced: 2024-05-15T19:14:41.903Z (4 months ago)
- Topics: calendar, macos, reminders
- Language: Ruby
- Homepage:
- Size: 3.62 MB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://badge.fury.io/rb/icalPal)
# 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](https://www.ruby-lang.org/) 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](https://github.com/ali-rantakari/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 as ```icalPal -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](https://iterm2.com/).
* ```--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](https://dianne.skoll.ca/projects/remind/) format uses a minimal implementation built in icalPal.
Other formats such as ANSI, HTML, Markdown, RDoc, and TOC, use Ruby's
[RDoc::Markup](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup.html)
framework to build and render the items.
Each item to be printed is a new
[RDoc::Markup::Document](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Document.html).
When using one of the separate by options, a section header is added first. The section contains:
* [RDoc::Markup::BlankLine](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/BlankLine.html)
(unless this is the first section)
* RDoc::Markup::Heading (level 1)
* [RDoc::Markup::Rule](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Rule.html)
The rest of the document is a series of
[RDoc::Markup::List](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/List.html)
objects, one for each of the item's properties:
* [RDoc::Markup::List](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/List.html)
* RDoc::Markup::Heading (level 2)
* [RDoc::Markup::BlankLine](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/BlankLine.html)
* [RDoc::Markup::ListItem](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/ListItem.html)
* [RDoc::Markup::Paragraph](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Paragraph.html)
The document will also include a number of
[RDoc::Markup::Verbatim](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Verbatim.html)
and
[RDoc::Markup::Raw](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Raw.html)
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](https://www.tynsoe.org/geektool/) and
[Übersicht](https://tracesof.net/uebersicht/).
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](https://github.com/jimlawton) 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*.