Overview#

ics-query is a command line tool for querying RFC 5545 .ics calendar files. You give it a time and a calendar file, and it gives you back the matching components as ICS output.

It handles recurring events, timezones, and the three standard component types: events (VEVENT), to-dos (VTODO), and journal entries (VJOURNAL). You can also query alarms (VALARM) separately.

How it works#

ics-query reads one or more .ics files, expands all recurring components into their individual occurrences, filters them by the time you specify, and writes the result to a file or stdout.

Three libraries do the heavy lifting:

  • recurring-ical-events expands recurring events and handles RFC 5545 recurrence rules.

  • icalendar parses and serialises .ics files.

  • x-wr-timezone handles the non-standard X-WR-TIMEZONE property used by some calendar apps.

Occurrence calculation#

An event can span multiple days. If you query a time window smaller than the event, the event still appears in the result as long as it overlaps with your query.

event.DTSTART <= span.DTEND  and  span.DTSTART < event.DTEND

Start is inclusive. End is exclusive.

When to use it#

  • You have .ics files and want to extract what is happening in a given period.

  • You want to pipe calendar data into shell scripts or other tools.

  • You need to filter a large calendar down to a specific component type.

  • You want to check what a recurring event produces for a specific date without opening a calendar app.

Planned features#

These features are planned but not yet implemented.

--select-index — Use an index or range to select which occurrence to return. Examples: 0,2,4 or 0-10.

--select-uid — Filter occurrences by UID.

Edit events — Edit occurrences to produce new ICS files.

Notifications — Use ics-query together with cron to get notified about upcoming events. For example: how many to-dos are in the next hour, how many events today, or a reminder to write a journal entry.