{"id":16033007,"url":"https://github.com/niccokunzmann/ics-query","last_synced_at":"2026-02-27T04:06:03.472Z","repository":{"id":254047392,"uuid":"845322562","full_name":"niccokunzmann/ics-query","owner":"niccokunzmann","description":"Find out what happens when in ICS calendar files - query RFC 5545 files for events, journals, TODOs and more","archived":false,"fork":false,"pushed_at":"2026-02-18T19:30:43.000Z","size":179,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T23:55:19.184Z","etag":null,"topics":["calculation","cmd","command","event","hacktoberfest","icalendar","ics","journal","query","shell","todo"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niccokunzmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["niccokunzmann"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://polar.sh/niccokunzmann"]}},"created_at":"2024-08-21T02:59:46.000Z","updated_at":"2026-02-18T19:30:31.000Z","dependencies_parsed_at":"2025-02-13T20:20:11.343Z","dependency_job_id":"4985b24b-83c1-4ca7-99e4-23ebe5c6eb14","html_url":"https://github.com/niccokunzmann/ics-query","commit_stats":null,"previous_names":["niccokunzmann/ics-query"],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/niccokunzmann/ics-query","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niccokunzmann%2Fics-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niccokunzmann%2Fics-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niccokunzmann%2Fics-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niccokunzmann%2Fics-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niccokunzmann","download_url":"https://codeload.github.com/niccokunzmann/ics-query/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niccokunzmann%2Fics-query/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29884515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calculation","cmd","command","event","hacktoberfest","icalendar","ics","journal","query","shell","todo"],"created_at":"2024-10-08T21:41:30.805Z","updated_at":"2026-02-27T04:06:03.457Z","avatar_url":"https://github.com/niccokunzmann.png","language":"Python","funding_links":["https://github.com/sponsors/niccokunzmann","https://polar.sh/niccokunzmann","https://opencollective.com/open-web-calendar/updates/calendar-calculation-on-the-command-line-ics-query","https://opencollective.com/open-web-calendar/","https://polar.sh/niccokunzmann/ics-query","https://thanks.dev"],"categories":[],"sub_categories":[],"readme":"# ics-query\n\n[![GitHub Actions CI](https://github.com/niccokunzmann/ics-query/actions/workflows/tests.yml/badge.svg)][GitHub Actions]\n[![PyPI Version](https://badge.fury.io/py/ics-query.svg)][PyPI]\n[![PyPI Downloads](https://img.shields.io/pypi/dm/ics-query.svg)][PyPI]\n[![Support on Open Collective](https://img.shields.io/opencollective/all/open-web-calendar?label=support%20on%20open%20collective)][Open Collective]\n[![Fund Issues with Polar](https://img.shields.io/github/issues/niccokunzmann/ics-query?logo=github\u0026label=issues%20seek%20funding\u0026color=%230062ff)][Polar]\n\n\u003c!-- Change description also in pyproject.toml --\u003e\nFind out what happens in ICS calendar files - query and filter RFC 5545 compatible `.ics` files for events, journals, TODOs and more.\n\n## Installation\n\nYou can install this package from the [PyPI].\n\n```shell\npip install ics-query\n```\n\nFor **Windows**, you can download `ics-query.exe` from our [Releases].\nFor **MacOS**, you can use brew:\n\n```shell\nbrew install niccokunzmann/tap/ics-query\n```\n\n## Support\n\n- Support using [GitHub Sponsors]\n- Fund specific issues using [Polar]\n- Support using [Open Collective]\n- Support using [thanks.dev]\n\nWe accept donations to sustain our work, once or regular.\nConsider donating money to open-source as everyone benefits.\n\n## Supported Features\n\nThis library is based on\n\n- [recurring-ical-events]\n- [icalendar]\n- [x-wr-timezone]\n\n[recurring-ical-events]: https://pypi.org/project/recurring-ical-events/\n[icalendar]: https://pypi.org/project/icalendar/\n[x-wr-timezone]: https://pypi.org/project/x-wr-timezone/\n\nFor a list of supported features and RFC compatibility,\nplease refer to their documentation, too.\n\n## Usage\n\n`ics-query` is a command line tool that aims to make icalendar occurance calculations\naccessible and easy.\nThis section walks you though the different functionalities.\n\n```shell\nics-query --help\n```\n\n### Examples\n\nYou can get a calendar from the web and see what is on.\nIn this example, we show which German National Holidays happening in August 2024:\n\n```shell\n$ wget -qO- 'https://www.calendarlabs.com/ical-calendar/ics/46/Germany_Holidays.ics' | ics-query at 2024-08 - -\nBEGIN:VEVENT\nSUMMARY:Assumption Day (BY\\, SL)\nDTSTART;VALUE=DATE:20240815\nDTEND;VALUE=DATE:20240815\nDTSTAMP:20231013T092513Z\nUID:65290cf9326601697189113@calendarlabs.com\nSEQUENCE:0\nDESCRIPTION:Visit https://calendarlabs.com/holidays/us/the-assumption-of-m\n ary.php to know more about Assumption Day (BY\\, SL). \\n\\n Like us on Faceb\n ook: http://fb.com/calendarlabs to get updates\nLOCATION:Germany\nSTATUS:CONFIRMED\nTRANSP:TRANSPARENT\nEND:VEVENT\n```\n\nIn the following example, we query a calendar file and print the result.\n\n```shell\n$ ics-query at 2019-03-04 one-event.ics -\nBEGIN:VEVENT\nSUMMARY:test1\nDTSTART;TZID=Europe/Berlin:20190304T080000\nDTEND;TZID=Europe/Berlin:20190304T083000\nDTSTAMP:20190303T111937\nUID:UYDQSG9TH4DE0WM3QFL2J\nCREATED:20190303T111937\nLAST-MODIFIED:20190303T111937\nEND:VEVENT\n```\n\n#### Concatenating Calendars\n\nWe can concatenate calendars and pipe them into `ics-query`.\nIn the example below, we get all events that happen right now in two calendars.\n\n```shell\n$ cat calendar1.ics calendar2.ics | ics-query at `date +%Y%m%d%H%M%S` - -\nBEGIN:VEVENT\n...\n```\n\n#### Piping calendars\n\nYou can pipe one or more calendars into the input.\n\n```shell\ncat calendar.ics | ics-query first -\n```\n\n#### Valid ICS files\n\nThe resulting events are missing the timezone and the calendar information by default.\nThis information can be added using the `--as-calendar` parameter.\nThe result is a valid `.ics` file that can be processed further by other commands and programs.\n\nIn the example below, we use the calendar command to inspect the event for human readability.\n\n```shell\n$ ics-query at --as-calendar 2014-05-03 x-wr-timezone-rdate-hackerpublicradio.ics event.ics\n$ icalendar event.ics\n    Organizer: \n    Attendees:\n\n    Summary    : HPR Community News\n    Starts     : Sat May  3 20:00:00 2014\n    End        : Sat May  3 22:00:00 2014\n    Duration   : 2:00:00\n    Location   : mumble.openspeak.cc port: 64747\n    Comment    : \n    Description:\n     This is from http://www.hackerpublicradio.org/eps/hpr1286/iCalendar_Hacking_shownotes.html\n```\n\n### Events at Certain Times\n\nYou can query which events happen at certain times:\n\n```shell\nics-query at TIME calendar.ics -\n```\n\nThe format of TIME:\n\n| TIME | description |\n| ------- | ----------- |\n| `2019`    | the whole year 2019 |\n| `2019-08` | August 2019 |\n| `2019-08-12` | 12th of August 2019 |\n| `2019-08-12T17` | 17:00-18:00 at the 12th of August 2019 |\n| `2019-08-12T17:20` | 17:20-17:21 at the 12th of August 2019 |\n| `2019-08-12T17:20:00` | 17:20 at the 12th of August 2019 |\n\n\nPlease see the command documentation for more help:\n\n```shell\nics-query at --help\nics-query --help\n```\n\nYou can get all **events** that happen at a certain **day**.\n\n```shell\nics-query at --components VEVENT 2029-12-24 calendar.ics\n```\n\nYou can get all **events** that happen **today**.\n\n```shell\nics-query at --components VEVENT `date +%Y-%m-%d` calendar.ics\n```\n\nYou can get all **TODO**s that happen in a certain **month**.\n\n```shell\nics-query at --components VTODO 2029-12-24 calendar.ics\n```\n\n### Events within a Time Span\n\nYou can query which events happen between certain times:\n\n```shell\nics-query between START END calendar.ics -\nics-query between START DURATION calendar.ics -\n```\n\nPlease see the command documentation for more help:\n\n```shell\nics-query between --help\nics-query --help\n```\n\nThe format of START and END with examples:\n\n| START or END | Description |\n| ------- | ----------- |\n| `2019`    | the whole year 2019 |\n| `2019-08` | August 2019 |\n| `2019-08-12` | 12th of August 2019 |\n| `2019-08-12T17` | 17:00-18:00 at the 12th of August 2019 |\n| `2019-08-12T17:20` | 17:20-17:21 at the 12th of August 2019 |\n| `2019-08-12T17:20:00` | 17:20 at the 12th of August 2019 |\n\nInstead of an absolute time, you can specify a duration after the START.\nThe `+` is optional.\n\n| DURATION | Description |\n| ------- | ----------- |\n| `+1d`   | one more day |\n| `+1h`   | one more hour |\n| `+1m`   | one more minute |\n| `+1s`   | one more second |\n| `+3600s`   | one more hour or 3600 seconds |\n| `+5d10h`   | five more days and 10 more hours |\n\n### Time Span Examples\n\nThis example returns the occurrences within the **next week**:\n\n```shell\nics-query between `date +%Y%m%d` +7d calendar.ics -\n```\n\nThis example saves the **events** from the **1st of May 2024 to the 10th of June** in\nevents.ics:\n\n```shell\nics-query between --component VEVENT 2024-5-1 2024-6-10 calendar.ics events.ics\n```\n\nIn this example, you can check what is happening on **New Years Eve 2025** around\nmidnight:\n\n```shell\nics-query between 2025-12-31T21:00 +6h calendar.ics events.ics\n```\n\n### `ics-query all` - the whole calendar\n\nYou can get everything that is happening in a calendar but that can be a lot!\n\n```shell\nics-query all calendar.ics\n```\n\n### Filtering Components\n\nWe support different component types: `VEVENT`, `VJOURNAL` and `VTODO`.\nBy default, we include all types in the result.\n\nYou can specify which components you would like to get using the\n`--component` or `-c` parameter.\n\n```shell\n-c VEVENT   # only events\n-c VTODO    # only TODOs\n-c VJOURNAL # only journal entries\n-c VALARM   # only components with the calculated alarm\n-c VEVENT -c VTODO # only events and journal entries\n```\n\nThis example returns the first event of a calendar.\n\n```shell\nics-query first -c VEVENT calendar.ics -\n```\n\nThis option is also available as `ICS_QUERY_COMPONENT` variable.\n\n```shell\nexport ICS_QUERY_COMPONENT=VEVENT\n# from now on, you will get only events\nics-query first calendar.ics\n```\n\nPlease see the command documentation for more help:\n\n```shell\nics-query --help\n```\n\n### Alarms\n\nAlarms are special because they do not occur alone.\nThey are located inside another component like a VEVENT or VTODO.\n\nConsiderations:\n\n- If you query a time span, the component might actually happen outside of the time span\n  but the alarm happens within the timespan.\n- Absolute alarms may only be included once and not for every occurrence.\n- Each resulting occurrence only has one alarm in them.\n- Do not mix `-c VEVENT` and others with `-c VALARM` or you might not know if\n  the alarm or the component is inside the time span.\n\nAs an example, if you want to get all alarms and the event summary that they are for,\nyou would be interested in the `SUMMARY` of the event and the `TRIGGER` of the alarm.\n\n```sh\n$ ics-query all -c VALARM --tz Europe/London alarm_1_week_before_event.ics - | grep -E 'TRIGGER|SUMMARY'\nSUMMARY:Event with an alarm 1 week before this starts        \u003c-- Event summary\nTRIGGER;TZID=Europe/London:20241202T110000                   \u003c-- Time of the alarm\nSUMMARY:Event with an alarm 1 week before this starts        \u003c-- Event summary\nTRIGGER;TZID=Europe/London:20241207T110000                   \u003c-- Time of the alarm\n```\n\n### Timezones\n\nYou can set the timezone of the query, otherwise the event's local timezone is used and you\nmight miss events in your own timezone.\n\nThe first event at New Year 2000 in the **event's local time**:\n\n```shell\nics-query at 2000-01-01 calendar.ics\n```\n\nThe first event at New Year 2000 in **your local time**:\n\n```shell\nics-query at --tz=localtime 2000-01-01 calendar.ics\n```\n\nThe first event at New Year 2000 in **UTC**:\n\n```shell\nics-query at --tz=UTC 2000-01-01 calendar.ics\n```\n\nThe first event at New Year 2000 in **Berlin time**:\n\n```shell\nics-query at --tz=Europe/Berlin 2000-01-01 calendar.ics\n```\n\nYou can also use the `ICS_QUERY_TZ` variable.\n\n```shell\nexport ICS_QUERY_TZ=localtime\n# from now on, we use your local time\nics-query at 2000-01-01 calendar.ics\n```\n\nFor all avaiable timezones see:\n\n```shell\nics-query --available-timezones\n```\n\nPlease see the command documentation for more help:\n\n```shell\nics-query --help\n```\n\n## Version Fixing\n\nIf you use this library in your code, you may want to make sure that\nupdates can be received but they do not break your code.\nThe version numbers are handeled this way: `a.b.c` example: `0.1.12`\n\n- `c` is changed for each minor bug fix.\n- `b` is changed whenever new features are added.\n- `a` is changed when the interface or major assumptions change that may break your code.\n\nSo, I recommend to version-fix this library to stay with the same `a`\nwhile `b` and `c` can change.\n\n## Development\n\nThis section should set you up for developing `ics-query`.\n\nTo create new commits, you should install [pre-commit](https://pre-commit.com/).\nThen run:\n\n```shell\npre-commit install\n```\n\n### Testing\n\nThis project's development is driven by tests.\nTests assure a consistent interface and less knowledge lost over time.\nIf you like to change the code, tests help that nothing breaks in the future.\nThey are required in that sense.\nExample code and ics files can be transferred into tests and speed up fixing bugs.\n\nYou can view the tests in the [test folder](https://github.com/niccokunzmann/ics-query/tree/main/ics_query/tests)\nIf you have a calendar ICS file for which this library does not\ngenerate the desired output, you can add it to the ``test/calendars``\nfolder and write tests for what you expect.\nIf you like, [open an issue](https://github.com/niccokunzmann/ics-query/issues) first, e.g. to discuss the changes and\nhow to go about it.\n\nTo run the tests, we use `tox`.\n`tox` tests all different Python versions which we want to  be compatible to.\n\n```shell\npip3 install tox\n```\n\nTo run all the tests:\n\n```shell\ntox\n```\n\nTo run the tests in a specific Python version:\n\n```shell\ntox -e py39\n```\n\nWe use ``ruff`` to format the code.\nRun this to format the code and show problems:\n\n```shell\ntox -e ruff\n```\n\n### New Release\n\nRenovate updates the dependencies automatically on the `main` branch.\nNew commits on `main` are automatically published with an increased\nPATCH version number.\n\nTo release a new version with a new MINOR or MAJOR version number change,\nfollow these steps:\n\n1. edit the Changelog Section\n2. create a commit and push it\n3. wait for [GitHub Actions] to finish the build\n4. create a tag and push it\n\n    ```shell\n    git tag v0.1.0\n    git push origin v0.1.0\n    ```\n\n5. Notify the issues about their release\n\n## Changelog\n\nWe automatically release the versions that only update dependencies.\nIf the version you installed does not show up here, only the dependencies\nhave been updated.\n\n- v0.4.37\n\n  - Test and support Python 3.13. See [Issue 9](https://github.com/niccokunzmann/ics-query/issues/9).\n\n- v0.4.36\n\n  - Test and document `VALARM`. See [Issue 16](https://github.com/niccokunzmann/ics-query/issues/16).\n\n- v0.4.33\n\n  - Add `--as-calendar` parameter.\n\n- v0.4.32\n\n  - Update dependencies.\n  - Include recurrence ID in events to identify the occurrence in a series.\n  - Update help message in command line.\n\n- v0.4.1\n\n  - Automatic release with patch level version number increased\n  - Increase patch version instead of minor version for automatic releases\n\n- v0.3.4\n\n  - Update dependencies\n  - Start automatic release of dependencies increasing the version number\n\n- v0.3.3b\n\n  - Update dependencies\n\n- v0.3.2b\n\n  - Fix that `--tz localtime` would use `localtime` as timezone name instead of the local timezone name.\n  - Fix tests on Windows\n  - Add Windows .exe build artifact\n\n- v0.3.1b\n\n  - Add `--license` option\n\n- v0.3.0b\n\n  - Add `--tz` timezone parameter\n  - Add `ics-query all` to get all occurrences\n\n- v0.2.1a\n\n  - Add `--component` to filter component types VEVENT, VJOURNAL and VTODO\n\n- v0.2.0a\n\n  - Add `ics-query first \u003ccalendar\u003e \u003coutput\u003e` for earliest occurrences\n  - Add `ics-query between \u003cspan_start\u003e \u003cspan_stop\u003e \u003ccalendar\u003e \u003coutput\u003e` to query time ranges\n\n- v0.1.1a\n\n  - Add `--version`\n  - Add `ics-query at \u003cdate\u003e \u003ccalendar\u003e \u003coutput\u003e`\n  - Add support for multiple calendars in one input\n\n- v0.1.0a\n\n  - Update Python version compatibility\n  - Add development documentation\n\n- v0.0.1a\n\n  - first version\n\n## Related Work\n\n- [icalendar-events-cli](https://github.com/waldbaer/icalendar-events-cli#readme) - another command line impementation of `recurring-ical-events`\n- [icalBuddy](https://hasseg.org/icalBuddy/)\n- [Blog Post](https://opencollective.com/open-web-calendar/updates/calendar-calculation-on-the-command-line-ics-query)\n- [#icsquery on mastodon](https://toot.wales/tags/icsquery)\n\n## Vision\n\nThis section shows where we would like to get to.\n\n### `ics-query --select-index` - reduce output size\n\nExamples: `0,2,4` `0-10`\n\n\n### `ics-query --select-uid` - filter by uid\n\n### How to edit an event\n\nTo edit a component like an event, you can append it to the calendar and increase the sequence number.\n\nExample:\n\n1. get the event `--select-index=0`\n2. change the summary\n3. increase sequence number\n4. add the event to the end of the calendar file\n5. show that the occurrence has changed\n\n\n### Notifications\n\nExamples:\n\n- There are x todos in the next hour\n- There are x events today\n- Please write a journal entry!\n\n[PyPI]: https://pypi.org/project/ics-query/\n[GitHub Actions]: https://github.com/niccokunzmann/ics-query/actions\n[Open Collective]: https://opencollective.com/open-web-calendar/\n[Polar]: https://polar.sh/niccokunzmann/ics-query\n[GitHub Sponsors]: https://github.com/sponsors/niccokunzmann\n[thanks.dev]: https://thanks.dev\n[Releases]: https://github.com/niccokunzmann/ics-query/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniccokunzmann%2Fics-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniccokunzmann%2Fics-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniccokunzmann%2Fics-query/lists"}