Examples#

ics-query takes a command, a time argument, one or more calendar files, and an output. Pass - as the calendar to read from stdin. Pass - as the output to write to stdout.

ics-query at 2019-03-04 calendar.ics -

Events at a specific time#

Use at to get all occurrences at a date, month, year, or precise time.

Get everything happening on a specific day:

ics-query at 2019-03-04 calendar.ics -

Get everything happening this month:

ics-query at `date +%Y-%m` calendar.ics -

Get everything happening right now (to the second):

ics-query at `date +%Y%m%d%H%M%S` calendar.ics -

Accepted time formats for at and for the START argument of between:

Format	Description
`2019`	all of 2019
`2019-08`	August 2019
`2019-08-12`	12 August 2019
`2019-08-12T17`	17:00 to 18:00 on 12 August 2019
`2019-08-12T17:20`	17:20 to 17:21 on 12 August 2019
`2019-08-12T17:20:00`	exactly 17:20:00 on 12 August 2019

Compact formats without separators are also accepted: 20190812, 20190812T1720, 201908121720.

Events within a time span#

Use between to get occurrences between a start and an end. Start is inclusive, end is exclusive.

Get events in the next 7 days:

ics-query between `date +%Y%m%d` +7d calendar.ics -

Get events between two specific dates:

ics-query between 2024-05-01 2024-06-10 calendar.ics events.ics

Get events around New Year’s Eve midnight:

ics-query between 2025-12-31T21:00 +6h calendar.ics -

The END argument can be a relative duration after START:

Duration	Description
`+1d`	one day
`+1h`	one hour
`+1m`	one minute
`+1s`	one second
`+3600s`	one hour as seconds
`+5d10h`	five days and 10 hours

The + prefix is optional.

First occurrence#

Use first to get only the first occurrence in each calendar file.

ics-query first calendar.ics -

All occurrences#

Use all to get every occurrence in a calendar.

ics-query all calendar.ics -

Calendars with recurring events can produce a very large number of occurrences. Use head to limit the output:

ics-query all calendar.ics - | head -100

Filtering by component type#

By default, ics-query returns VEVENT, VTODO, and VJOURNAL components. Use -c or --component to filter.

Only events:

ics-query at 2024-08 -c VEVENT calendar.ics -

Only to-dos:

ics-query at 2024-08 -c VTODO calendar.ics -

Only journal entries:

ics-query at 2024-08 -c VJOURNAL calendar.ics -

Pass -c multiple times to include more than one type:

ics-query at 2024-08 -c VEVENT -c VTODO calendar.ics -

You can also set the component via environment variable:

export ICS_QUERY_COMPONENT=VEVENT
ics-query at 2024-08 calendar.ics -

Querying alarms#

Use -c VALARM to query components by their alarm times. VALARM is not included in the default output.

Alarms behave differently from other components:

The parent component (VEVENT, VTODO) may fall outside the queried time span while the alarm falls within it, and it will still be included.
Absolute alarms may appear only once, not for every recurrence.
Each result contains only one alarm.
Do not mix -c VALARM with other types. You will not be able to tell whether the alarm or the parent component matched the time span.

Get all alarms and show their trigger time and event summary:

ics-query all -c VALARM calendar.ics - | grep -E 'TRIGGER|SUMMARY'

Timezones#

By default, ics-query uses each component’s own timezone. Two events at 6am in different timezones both appear when you query by date, even though they are hours apart in absolute time.

Use --tz to query in a specific timezone:

ics-query at --tz=Europe/Berlin 2024-08-20 calendar.ics -

Use --tz=localtime to query in your local system timezone:

ics-query at --tz=localtime 2024-08-20 calendar.ics -

Use --tz=UTC for UTC:

ics-query at --tz=UTC 2024-08-20 calendar.ics -

Set the timezone via environment variable:

export ICS_QUERY_TZ=Europe/Berlin
ics-query at 2024-08-20 calendar.ics -

List all available timezone names:

ics-query --available-timezones

Valid ICS output#

By default, the output contains only the matched components with no VCALENDAR wrapper and no VTIMEZONE. This is intentional for piping into other tools.

To produce a valid .ics file that calendar applications can open, use --as-calendar:

ics-query at --as-calendar 2014-05-03 calendar.ics output.ics

The output is wrapped in a VCALENDAR block and includes any VTIMEZONE components from the source calendar.

You can also set this via environment variable:

export ICS_QUERY_AS_CALENDAR=1
ics-query at 2014-05-03 calendar.ics output.ics

Multiple calendars#

Pass multiple files directly:

ics-query at 2024-08 calendar1.ics calendar2.ics -

Or concatenate them through stdin:

cat calendar1.ics calendar2.ics | ics-query at 2024-08 - -

Fetching a calendar from the web#

wget -qO- 'https://example.com/calendar.ics' | ics-query at 2024-08 - -