Command-line tool to read icalendar events

Introduction

This command-line tool allows users to query and filter iCalendar (RFC 5545) or jCal (RFC 7265) or calendars.

It leverages the excellent icalendar and recurring-ical-events libraries for parsing and querying the calendar contents.

Leveraging the powerful jsonargparse library, this tool supports configuration and control via command-line parameters or a JSON configuration file.

Features

• Download and parse iCalendar files
  • from remote HTTP URL (https://<path to icalendar server>)
  • from local file URL (file://<abs. path to local iCalendar/ICS or jCal file>)
• Filtering
  • by start- and end-date range
  • by event summary, description or location text (RegEx match)
• Different Outputs
  • Formats: JSON, jCal (RFC 7265), human-readable (pretty printed)
  • Targets: shell (stdout), file

Changelog

Changes can be followed at CHANGELOG.md.

Requirements

• Python 3.10
• pip or pipx

For development:

• python-pdm (package dependency manager)

Setup

With pip / pipx

pip install icalendar-events-cli
pipx install icalendar-events-cli

Setup directly from github repo / clone

git clone https://github.com/waldbaer/icalendar-events-cli.git
cd icalendar-events-cli

python -m venv .venv
source ./.venv/bin/activate
pip install .

Usage

All parameters can be provided either as command-line arguments or through a JSON configuration file (default: config.json). A combination of both methods is also supported.

A common approach is to define the calendar URL and HTTP authentication credentials in the JSON configuration file, while specifying filters as command-line arguments. Alternatively, you can define all credentials via command-line parameters or include the applied filters directly in the JSON configuration file.

The results of all executed queries are returned in human-readable (pretty-printed) or machine-readable JSON format. This output can be displayed directly on the shell (stdout) or saved to a file.

The machine-readable JSON output format is designed for seamless integration with automation platforms, such as Node-RED, which typically execute the icalendar-events-cli tool.

Examples

Example 1: Query Public Holiday Calendar

• Use human-readable output format
• Pass all parameters as command-line arguments

icalendar-events-cli --calendar.url https://www.thunderbird.net/media/caldata/autogen/GermanHolidays.ics \
  --filter.start-date $(date +%Y)-01-01T02:00:00+02:00 \
  --filter.end-date $(date +%Y)-12-31T02:00:00+01:00 \
  --filter.summary ".*(Weihnacht|Oster).*"
Start Date:         2026-01-01T02:00:00+02:00
End Date:           2026-12-31T02:00:00+01:00
Summary Filter:     .*(Weihnacht|Oster).*
Number of Events:   3

2026-04-05T00:00:00+02:00 -> 2026-04-05T23:59:59+02:00 [86399 sec]     | Ostersonntag  (Brandenburg) | Description: Common local holiday -  Der Ostersonntag ist laut der christlichen Bibel ein Feiertag in Deutschland, um die Auferstehung Jesu Christi zu feiern.
2026-04-06T00:00:00+02:00 -> 2026-04-06T23:59:59+02:00 [86399 sec]     | Ostermontag  | Description: Christian -  Viele Menschen in Deutschland begehen jährlich den Ostermontag am Tag nach dem Ostersonntag. Es ist in allen Bundesstaaten ein Feiertag.
2026-12-25T00:00:00+01:00 -> 2026-12-25T23:59:59+01:00 [86399 sec]     | Weihnachten  | Description: Christian -  Der Weihnachtstag markiert die Geburt Jesu Christi und ist ein gesetzlicher Feiertag in Deutschland. Es ist jedes Jahr am 25. Dezember.

Example 2: Query School Vacation Calendar

The machine-readable JSON output format is designed for seamless integration with automation platforms, such as Node-RED, which typically execute the icalendar-events-cli tool.

• Use JSON output format
• Mixed parameter configuration: Pass only end-date as command-line argument.

Create school-summer-vacation.json containing calendar URL, summary filter and output format settings:

{
  "calendar" : {
      "url" : "https://www.feiertage-deutschland.de/kalender-download/ics/schulferien-baden-wuerttemberg.ics",
      "verify_url": true
  },
  "filter": {
    "summary": "Sommer.*"
  },
  "output": {
    "format": "json"
  }
}

Query the calendar for summer vacation until end of next year:

icalendar-events-cli --config school-summer-vacation.json \
  --filter.end-date $(($(date +%Y) + 1))-12-31T23:59:59

{
  "filter": {
    "start-date": "2025-01-25T11:09:20+01:00",
    "end-date": "2026-12-31T23:59:59+01:00",
    "summary": "Sommer.*"
  },
  "events": [
    {
      "start-date": "2025-07-31T00:00:00+02:00",
      "end-date": "2025-09-13T23:59:59+02:00",
      "summary": "Sommerferien Baden-Württemberg 2025",
      "description": "Schulferien 2025: https://www.feiertage-deutschland.de/schulferien/2025/",
      "location": "BW"
    },
    {
      "start-date": "2026-07-30T00:00:00+02:00",
      "end-date": "2026-09-12T23:59:59+02:00",
      "summary": "Sommerferien Baden-Württemberg 2026",
      "description": "Schulferien 2026: https://www.feiertage-deutschland.de/schulferien/2026/",
      "location": "BW"
    }
  ]
}

Example 3: Convert iCalendar (RFC 5545) to jCal (RFC 7265) format

• Use jcal output format

icalendar-events-cli --calendar.url https://www.thunderbird.net/media/caldata/autogen/GermanHolidays.ics \
  --filter.start-date 1900-01-01T02:00:00+02:00 \
  --filter.end-date 2500-12-31T02:00:00+01:00 \
  --output.format jcal \
  --output.file ./GermanHolidays.json

Example jCal contents of the converted GermanHolidays.json. The passed filter criterias are added as x-filter-... attributes to the jCal output (x-filter-date-range, x-filter-summary, x-filter-description, x-filter-location).

[
  "vcalendar",
  [
    ...
    [
      "x-filter-date-range",
      {},
      "period",
      [
        "1900-01-01T02:00:00+02:00",
        "2500-12-31T02:00:00+01:00"
      ]
    ]
  ],
  [
    [
      "vevent",
      [
        [
          "summary",
          {},
          "text",
          "Neujahrstag "
        ],
  ...
]

Parse and filter the converted jCal calendar again producing same result as the first example.

icalendar-events-cli --calendar.url file://$(pwd)/GermanHolidays.json \
  --filter.start-date $(date +%Y)-01-01T02:00:00+02:00 \
  --filter.end-date $(date +%Y)-12-31T02:00:00+01:00 \
  --filter.summary ".*(Weihnacht|Oster).*"
Start Date:         2026-01-01T02:00:00+02:00
End Date:           2026-12-31T02:00:00+01:00
Summary Filter:     .*(Weihnacht|Oster).*
Number of Events:   3

2026-04-05T00:00:00+02:00 -> 2026-04-05T23:59:59+02:00 [86399 sec]     | Ostersonntag  (Brandenburg) | Description: Common local holiday -  Der Ostersonntag ist laut der christlichen Bibel ein Feiertag in Deutschland, um die Auferstehung Jesu Christi zu feiern.
2026-04-06T00:00:00+02:00 -> 2026-04-06T23:59:59+02:00 [86399 sec]     | Ostermontag  | Description: Christian -  Viele Menschen in Deutschland begehen jährlich den Ostermontag am Tag nach dem Ostersonntag. Es ist in allen Bundesstaaten ein Feiertag.
2026-12-25T00:00:00+01:00 -> 2026-12-25T23:59:59+01:00 [86399 sec]     | Weihnachten  | Description: Christian -  Der Weihnachtstag markiert die Geburt Jesu Christi und ist ein gesetzlicher Feiertag in Deutschland. Es ist jedes Jahr am 25. Dezember.

All Available Parameters and Configuration Options

Details about all available options:

Usage: icalendar-events-cli [-h] [--version] [-c CONFIG] --calendar.url URL [--calendar.verify-url {true,false}] [--calendar.user USER] [--calendar.password PASSWORD] [-s START_DATE]
                            [-e END_DATE] [-f SUMMARY] [--filter.description DESCRIPTION] [--filter.location LOCATION] [--output.format {human_readable,json,jcal}] [-o FILE]

Command-line tool to read and filter events from iCalendar (RFC 5545) or jCal (RFC 7265) calendars. | Version 2.0.0 | Copyright 2023-2026

Default Config File Locations:
  ['./config.json'], Note: no existing default config file found.

Options:
  -h, --help            Show this help message and exit.
  --version             Print version and exit.
  -c, --config CONFIG   Path to JSON configuration file.
  --calendar.url URL    URL of the calendar (iCalendar or jCal format).
                        Also URLs to local files with schema file://<absolute path to local file> are supported. (required, type: None)
  --calendar.verify-url {true,false}
                        Configure SSL verification of the URL (type: None, default: True)
  --calendar.user USER  Username for calendar URL HTTP authentication (basic authentication) (type: None, default: None)
  --calendar.password PASSWORD
                        Password for calendar URL HTTP authentication (basic authentication) (type: None, default: None)
  -s, --filter.start-date START_DATE
                        Start date/time of event filter by time (ISO format). Default: now (type: datetime_isoformat, default: now)
  -e, --filter.end-date END_DATE
                        End date/time of event filter by time (ISO format). Default: end of today (type: datetime_isoformat, default: now)
  -f, --filter.summary SUMMARY
                        RegEx to filter calendar events based on the summary attribute. (type: regex_type, default: None)
  --filter.description DESCRIPTION
                        RegEx to filter calendar events based on the description attribute. (type: regex_type, default: None)
  --filter.location LOCATION
                        RegEx to filter calendar events based on the location attribute. (type: regex_type, default: None)
  --output.format {human_readable,json,jcal}
                        Output format. (type: None, default: human_readable)
  -o, --output.file FILE
                        Path of output file. If not set the output is written to console / stdout (type: None, default: None)

Development

Setup environment

pdm install --dev

Update dependencies to latest versions

pdm update --unconstrained --save-exact --no-sync

Format / Linter / Tests

# Check code style
pdm run format

# Check linter
pdm run lint

# Run tests
pdm run tests

Publish

Done automatically by github workflow / actions.

Acknowledgments

Special thanks to icalendar and recurring-ical-events for providing the core libraries that power this tool.