Skip to main content

icalcli

An iCalendar Command Line Interface

icalcli - a modification of gcalcli - is a Python command line front-end to your Calendar. It allows you to get your agenda, view weekly and monthly calendars (ascii text graphical calendar), search for events, add new events, delete events, and edit events.

Unlike gcalcli which is tied to Google Calendar, icalcli is agnostic to (abstracts away from) the actual backend calendar service. It relies on a backend interface which interacts with the backend calendar to perform all the CRUD (Create, Retrieve, Update and Delete) operations on the actual calendar. The package includes two backends:

  • The etesync_backend subpackage provides a backend interface to the EteSync calendar (versions 1.0 and 2.0). In fact, icalcli was created primarily to provide a command line interface to my self hosted EteSync calendar.

  • The file_backend subpackage provides a backend interface to a calendar contained in a local ics file. This is useful as a viewer/editor of ics files. It is also useful to try out icalci without having any other backend configured.

The two included backends would also be useful to those who wish to write their own backend interfaces. icalcli requires the calendar to be presented to it as a list of icalendar events (VEVENT). It is the responsibility of the backend interface to read the actual calendar and create this list of events. It must also perform all the CRUD (Create, Retrieve, Update and Delete) operations on the actual calendar.

Requirements

Optional packages

  • pyetesync the python client library for EteSync if you want to use the EteSync backend.

Installation

Install from PyPI

pip install icalcli

or via pipx:

pipx install icalcli

Install from source

git clone https://github.com/jrvarma/icalcli.git
cd icalcli
python -m pip install .

or via pipx:

pipx install . --editable

Usage

Command line arguments

icalcli provides a series of subcommands with the following functionality:

edit (e)               edit calendar events
agenda (g)             get an agenda for a time period
calw (w)               get a week-based agenda in calendar format
cal5w (5w)             get this week / 2 past / 2 future weeks agenda in calendar format
calm (m)               get a month agenda in calendar format
add (a)                add a detailed event to the calendar
search (s)             (regex) search for events 
sync (y)               sync the backend calendar
quit (q)               quit icalcli

By default, icalcli runs interactively as an REPL (Read Evaluate Print Loop). Run icalcli --help for more details. icalcli <subcommand> --help gives help on each subcommand.

Configuration Script

In the beginning, icalcli executes a configuration script which is expected to create the object backend_interface representing the backend interface initialized with the right authentication credentials to access the backend calendar. The configuration script is located, by default, at ~/.icalcli.py, but this can be changed with the -c option.

Example configuration for file_backend

from icalcli import ICSInterface

backend_interface = ICSInterface("/path/to/ics-file")

Example configuration for multiple readonly file_backend

from icalcli import ICSInterface

backend_interface = ICSInterface(["/path/to/ics-file-1", "/path/to/ics-file-2"])

Example configuration for etesync_backend (etesync 1.0)

This configuration assumes that all the credentials are stored in a plain text (json) file. In practice, you would use a more secure storage (perhaps, the Gnome keyring) or just read it from the terminal.

from icalcli import EtesyncInterface
import base64
import json

conf_file = '/path/to/json-file'
with open(conf_file, 'r') as fp:
    c = json.load(fp)
backend_interface = EtesyncInterface(
    c['email'], c['userPassword'], c['remoteUrl'],
    c['uid'], c['authToken'],
    base64.decodebytes(c['cipher_key'].encode('ascii')))

See the Example code for getting the uid and authToken for the etesync calendar.

Example configuration for etebase_backend (etesync 2.0)

This configuration assumes that all the credentials are stored in a plain text (json) file. In practice, you would use a more secure storage (perhaps, the Gnome keyring) or just read it from the terminal.

from icalcli import EtebaseInterface
import json

conf_file = '/path/to/json-file'
with open(conf_file, 'r') as fp:
    c = json.load(fp)

backend_interface = EtebaseInterface(c['user'], c['server_url'], c['password'],
                                     c['calendar_uid'], silent=False)

The calendar_uid can be obtained using the following code. This code assumes that the dict c has been populated with the credentials from the json file as above.

from etebase import Client, Account, FetchOptions

client = Client(c['user'], c['server_url'])
etebase = Account.login(client, c['user'], c['password'])
col_mgr = etebase.get_collection_manager()
print({col.uid: col.meta
      for col in col_mgr.list("etebase.vevent").data})

Recurring events and default search period

icalcli understands the RRULE, RDATE, EXRULE, EXDATE elements of the icalendar specification. These elements can be added while creating or editing events using --rrule, --rdate, --exrule and --exdate options.

In most views, the instances of the recurring event are displayed. Since a recurring event can have an unlimited number of instances, searches with no start or end date can produce an unending series of events. By default therefore searches with no start or end date are limited to the previous five years and following five years. These defaults can be changed using the options --default_past_years and --default_future_years

Raw ICS

The icalendar specification is quite large and complex, and icalcli implements only the most common parts of this specification. It is possible to use the --raw_ics option to create/edit event using raw ICS text.

Screenshots

Some screenshots are available at Github:

Agenda and Week Views

Agenda and Week Views

Adding an event

Adding an event

Searching and editing events

Searching and editing events

Multi-day events

Multi-day events

Month View

Month View

Metadata

Release files for icalcli 1.1.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for icalcli 1.1.6
File Size Uploaded Provenance Actions
icalcli-1.1.6.tar.gz 32.8 kB Without provenance Details for icalcli-1.1.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for icalcli 1.1.6
File Interpreter ABI Platform Actions
icalcli-1.1.6-py3-none-any.whl Python 3 none any Details for icalcli-1.1.6-py3-none-any.whl

Total release size: 68.3 kB

Release files / icalcli-1.1.6.tar.gz

Download URL icalcli-1.1.6.tar.gz
Size 32.8 kB
Tags Source
SHA-256 checksum
How to use checksums
4cf966990ee38d849c8ceb5e7ff3cdea5b9f545237c32fc6fddc6add356fd399
BLAKE2b-256 checksum
How to use checksums
3454f16a095ce47214aa8ec13e271dd860c8cd5793c38de99fc1b003807798c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.7

Release files / icalcli-1.1.6-py3-none-any.whl

Download URL icalcli-1.1.6-py3-none-any.whl
Size 35.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ab3cf4aa9547821065b36a3d2961113de906f1ce2c1c64533732a1fdd6cb349
BLAKE2b-256 checksum
How to use checksums
48a9b6cc6adcb0eb22266094712ac426ac79daed66368a8f62399f59360df7c1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.7

Security for icalcli 1.1.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page