{"id":13586814,"url":"https://github.com/ajrosen/icalPal","last_synced_at":"2025-04-07T18:35:04.821Z","repository":{"id":75745877,"uuid":"603181680","full_name":"ajrosen/icalPal","owner":"ajrosen","description":"Command-line tool to query the macOS Calendar and Reminders","archived":false,"fork":false,"pushed_at":"2024-05-15T00:51:15.000Z","size":3791,"stargazers_count":9,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-15T19:14:41.903Z","etag":null,"topics":["calendar","macos","reminders"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/ajrosen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2023-02-17T19:41:17.000Z","updated_at":"2024-08-01T16:32:51.745Z","dependencies_parsed_at":"2023-11-18T00:13:22.512Z","dependency_job_id":"880aa3f3-313b-4ecc-80a0-6cb837898d40","html_url":"https://github.com/ajrosen/icalPal","commit_stats":{"total_commits":18,"total_committers":3,"mean_commits":6.0,"dds":0.2777777777777778,"last_synced_commit":"17e8d3e3190b14888dec03867ac4c94eba349c7e"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajrosen%2FicalPal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajrosen%2FicalPal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajrosen%2FicalPal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajrosen%2FicalPal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajrosen","download_url":"https://codeload.github.com/ajrosen/icalPal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223261679,"owners_count":17115615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["calendar","macos","reminders"],"created_at":"2024-08-01T15:05:49.876Z","updated_at":"2025-04-07T18:35:04.811Z","avatar_url":"https://github.com/ajrosen.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"[![Gem Version](https://badge.fury.io/rb/icalPal.svg)](https://badge.fury.io/rb/icalPal)\n\n# icalPal\n\n## Description\n\nicalPal is a command-line tool to query a macOS Calendar and Reminders\ndatabases for accounts, calendars, events, and tasks.  It can be run\non any system with [Ruby](https://www.ruby-lang.org/) and access to a\nCalendar or Reminders database.\n\n## Installation\n\nAs a system-wide Ruby gem:\n\n```\ngem install icalPal\n```\n\nor in your home diretory:\n\n```\ngem install --user-install icalPal\n```\n\nAs a Homebrew formula:\n\n```\nbrew tap ajrosen/icalPal\nbrew install icalPal\n```\n\n## Features\n\n### Compatability with [icalBuddy](https://github.com/ali-rantakari/icalBuddy)\n\nicalPal tries to be compatible with icalBuddy for command-line options\nand for output.  There are a some important differences to be aware\nof.\n\n* Options require two hyphens, except for single-letter options that require one hyphen\n* *eventsFrom* is not supported.  Instead there is *--from*, *--to*, and *--days*\n* *uncompletedTasks* is simply *tasks*\n* *undatedUncompletedTasks* is simply *undatedTasks*\n* *tasksDueBefore:DATE* is not yet supported\n* The command can go anywhere; it doesn't have to be the last argument\n* Property separators are comma-delimited\n\n### Additional commands\n\n```icalPal accounts```\n\nShows a list of enabled Calendar accounts.  Internally they are known as *Stores*; you can run ```icalPal stores``` instead.\n\n```icalPal datedTasks```\n\nShows only reminders that have a due date.\n\n### Additional options\n\n* 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```.\n* The ```-c``` part is optional, but you cannot abbreviate the command if you leave it off.\n* Use ```-o``` to print the output in different formats.  CSV or JSON are intertesting choices.\n* Copy your Calendar database file and use ```--db``` on it.\n* ```--it``` and ```--et``` will filter by Calendar *type*.  Types are **Local**, **Exchange**, **CalDAV**, **MobileMe**, **Subscribed**, and **Birthdays**\n* ```--il``` and ```-el``` will filter by Reminder list\n* ```--ia``` includes *only* all-day events (opposite of ```--ea```)\n* ```--aep``` is like ```--iep```, but *adds* to the default property list instead of replacing it.\n* ```--sep``` to separate by any property, not just calendar (```--sc```) or date (```--sd```)\n* ```--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/).\n* ```--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\n\nBecause 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.\n\n## Usage\n\nicalPal: Usage: icalPal [options] [-c] COMMAND\n\nCOMMAND must be one of the following:\n```\n    events                  Print events\n    tasks                   Print tasks\n    calendars               Print calendars\n    accounts                Print accounts\n\n    eventsToday             Print events occurring today\n    eventsToday+NUM         Print events occurring between today and NUM days into the future\n    eventsNow               Print events occurring at present time\n    datedTasks              Print tasks with a due date\n    undatedTasks            Print tasks with no due date\n```\n\nGlobal options:\n```\n    -c, --cmd=COMMAND       Command to run\n        --db=DB             Use DB file instead of Calendar (default: /Users/ajr/Library/Calendars/Calendar.sqlitedb)\n                            For the tasks commands this should be a directory containing .sqlite files\n                            (default: /Users/ajr/Library/Group Containers/group.com.apple.reminders/Container_v1/Stores)\n        --cf=FILE           Set config file path (default: /Users/ajr/.icalpal)\n    -o, --output=FORMAT     Print as FORMAT (default: default)\n                            [ansi, csv, default, hash, html, json, md, rdoc, remind, toc, xml, yaml]\n```\n\nIncluding/excluding calendars and reminders:\n```\n        --is=ACCOUNTS       List of accounts to include\n        --es=ACCOUNTS       List of accounts to exclude\n\n        --it=TYPES          List of calendar types to include\n        --et=TYPES          List of calendar types to exclude\n                            [Local, Exchange, CalDAV, MobileMe, Subscribed, Birthdays]\n\n        --ic=CALENDARS      List of calendars to include\n        --ec=CALENDARS      List of calendars to exclude\n\n        --il=LISTS          List of reminder lists to include\n        --el=LISTS          List of reminder lists to exclude\n\n        --match=FIELD=REGEXP\n                            Include only items whose FIELD matches REGEXP (ignoring case)\n```\n\nChoosing dates:\n```\n        --from=DATE         List events starting on or after DATE\n        --to=DATE           List events starting on or before DATE\n                            DATE can be yesterday, today, tomorrow, +N, -N, or anything accepted by DateTime.parse()\n                            See https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse\n\n    -n                      Include only events from now on\n        --days=N            Show N days of events, including start date\n        --sed               Show empty dates with --sd\n        --ia                Include only all-day events\n        --ea                Exclude all-day events\n```\n\nChoose properties to include in the output:\n```\n        --iep=PROPERTIES    List of properties to include\n        --eep=PROPERTIES    List of properties to exclude\n        --aep=PROPERTIES    List of properties to include in addition to the default list\n\n        --itp=PROPERTIES    List of task properties to include\n        --etp=PROPERTIES    List of task properties to exclude\n        --atp=PROPERTIES    List of task properties to include in addition to the default list\n                            Included for backwards compatability, these are aliases for --iep, --eep, and --aep\n\n        --uid               Show event UIDs\n        --eed               Exclude end datetimes\n\n        --nc                No calendar names\n        --npn               No property names\n        --nrd               No relative dates\n\n    Properties are listed in the order specified\n\n    Use 'all' for PROPERTIES to include all available properties (except any listed in --eep)\n    Use 'list' for PROPERTIES to list all available properties and exit\n```\n\nFormatting the output:\n```\n        --li=N              Show at most N items (default: 0 for no limit)\n\n        --sc                Separate by calendar\n        --sd                Separate by date\n        --sp                Separate by priority\n        --sep=PROPERTY      Separate by PROPERTY\n\n        --sort=PROPERTY     Sort by PROPERTY\n        --std               Sort tasks by due date (same as --sort=due_date)\n        --stda              Sort tasks by due date (ascending) (same as --sort=due_date -r)\n    -r, --reverse           Sort in reverse\n\n        --ps=SEPARATORS     List of property separators\n        --ss=SEPARATOR      Set section separator\n\n        --df=FORMAT         Set date format\n        --tf=FORMAT         Set time format\n                            See https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-i-strftime for details\n\n    -b, --bullet=STRING     Use STRING for bullets\n        --ab=STRING         Use STRING for alert bullets\n        --nb                Do not use bullets\n        --nnr=SEPARATOR     Set replacement for newlines within notes\n\n    -f                      Format output using standard ANSI colors\n        --color             Format output using a larger color palette\n```\n\nHelp:\n```\n    -h, --help              Show this message\n    -V, -v, --version       Show version and exit (2.0.0)\n    -d, --debug=LEVEL       Set the logging level (default: warn)\n                            [debug, info, warn, error, fatal]\n```\n\nEnvironment variables:\n```\n    ICALPAL                 Additional arguments\n    ICALPAL_CONFIG          Additional arguments from a file\n                            (default: /Users/ajr/.icalpal)\n```\n\n## Output formats\n\nicalPal supports several output formats.  The **default** format tries\nto mimic icalBuddy as much as possible.\n\nCSV, Hash, JSON, XML, and YAML print all fields for all items in their\nrespective formats.  From that you can analyze the results any way you\nlike.\n\n[Remind](https://dianne.skoll.ca/projects/remind/) format uses a minimal implementation built in icalPal.\n\nOther formats such as ANSI, HTML, Markdown, RDoc, and TOC, use Ruby's\n[RDoc::Markup](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup.html)\nframework to build and render the items.\n\nEach item to be printed is a new\n[RDoc::Markup::Document](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Document.html).\n\nWhen using one of the \u003cem\u003eseparate by\u003c/em\u003e options, a section header is added first.  The section contains:\n\n* [RDoc::Markup::BlankLine](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/BlankLine.html)\n  (unless this is the first section)\n* RDoc::Markup::Heading (level 1)\n* [RDoc::Markup::Rule](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Rule.html)\n\nThe rest of the document is a series of\n[RDoc::Markup::List](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/List.html)\nobjects, one for each of the item's properties:\n\n* [RDoc::Markup::List](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/List.html)\n* RDoc::Markup::Heading (level 2)\n* [RDoc::Markup::BlankLine](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/BlankLine.html)\n* [RDoc::Markup::ListItem](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/ListItem.html)\n* [RDoc::Markup::Paragraph](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Paragraph.html)\n\nThe document will also include a number of\n[RDoc::Markup::Verbatim](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Verbatim.html)\nand\n[RDoc::Markup::Raw](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Raw.html)\nitems.  They are not included in the output, but are used to pass\ninformation about the item and property to the default formatter.\n\n## History\n\nI used icalBuddy for many years.  It's great for scripting,\nautomation, and as a desktop widget for apps like\n[GeekTool](https://www.tynsoe.org/geektool/) and\n[Übersicht](https://tracesof.net/uebersicht/).\n\nAs with many applications, I started to run into some limitations in\nicalBuddy.  The biggest being that active development ended in 2014.\nIt's only thanks to the efforts of [Jim\nLawton](https://github.com/jimlawton) that it even compiles anymore.\n\nInstead of trying to understand and extend the existing code, I chose\nto start anew using my language of choice: Ruby.  Using Ruby meant\nthere is *much* less code; about 1,800 lines vs. 7,000.  It also means\nicalPal is multi-platform.\n\nI won't pretend to understand **why** you would want to run this on\nLinux or Windows.  But since icalPal is written in Ruby and gets its\ndata directly from the Calendar and Reminders database files instead\nof an API, you *can*.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajrosen%2FicalPal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajrosen%2FicalPal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajrosen%2FicalPal/lists"}