📅 Calendula

CLI to manage calendars

Table of contents

• Features
• Usage
  • List calendars
  • List calendar items
  • Edit calendar item
• Installation
• Configuration
  • Google
  • Apple
  • Microsoft
  • Posteo
• FAQ
• Sponsoring

Features

• CalDAV and Vdir support
• Native TLS support via native-tls crate (requires native-tls feature)
• Rust TLS support via rustls crate with:
  • AWS crypto support (requires rustls-aws feature)
  • Ring crypto support (requires rustls-ring feature)
• Shell command and keyring storages (requires command and keyring features)
• JSON support with --json

Calendula CLI is written in Rust, and relies on cargo features to enable or disable functionalities. Default features can be found in the features section of the Cargo.toml, or on docs.rs.

Usage

List calendars

$ calendula calendars list

┌─────────┬───────────────┬──────┬───────┐
│ ID      ┆ NAME          ┆ DESC ┆ COLOR │
╞═════════╪═══════════════╪══════╪═══════╡
│ default ┆ Clément DOUIN ┆      ┆       │
└─────────┴───────────────┴──────┴───────┘

List calendar items

$ calendula items list default

┌─────────────────────────────────────────┬──────────────────────┬─────────────────────────────────────────┬───────────────────────────┐
│ ID                                      ┆ DESC                 ┆ COMPONENTS                              ┆ DATE                      │
╞═════════════════════════════════════════╪══════════════════════╪═════════════════════════════════════════╪═══════════════════════════╡
│ 289e89c0-b351-4bc3-a7a4-4ababca26161    ┆ Appeler Didier       ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-12T18:20:36+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 005ca92b-211f-4c7e-8c18-0a3644ec8792    ┆ Garage               ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-07T13:54:57+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 9045759c-1752-45e2-a9ba-d0faa72d6750    ┆ Charlie              ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-07T13:54:57+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 5a90ec56-d5f6-4e03-b143-3c992e472e16    ┆ Ball-trap            ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-07T13:54:57+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 6df73dd4-aae7-437d-8438-6f052774d77a    ┆ Garage Dacia         ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-02T09:22:05+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 9de2158d-15ca-447d-b7cd-5e3e432d140d    ┆ Garage               ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-02T09:22:05+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 942db423-edcf-4ddb-a5e5-dac5b079ab3d    ┆ Garage Fiat          ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-10-02T09:22:05+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 02405656-00a3-4242-a7c2-0e668d39ca8e    ┆ Sage femme           ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-09-20T13:15:59+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 236b94a6-ee38-4b3e-a434-a4fd24d9c987    ┆ Internet             ┆ VCALENDAR, VEVENT, VALARM, VTIMEZONE,   ┆ 2025-09-20T13:11:56+00:00 │
│                                         ┆                      ┆ STANDARD, DAYLIGHT                      ┆                           │
└─────────────────────────────────────────┴──────────────────────┴─────────────────────────────────────────┴───────────────────────────┘

Edit calendar item

$ calendula item update default 62196d36-65cb-4a6b-b107-f3d8dc8d8b62

You text editor opens with the content of your iCalendar:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035900Z
SUMMARY:Fête à la Bastille
END:VEVENT
END:VCALENDAR

Once edition done, you should see the following message:

Item successfully updated

Installation

Pre-built binary

Calendula CLI can be installed with the installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/calendula/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/calendula/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

If you want a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. You should find a pre-built binary matching your OS. These pre-built binaries are built from the master branch, using default features.

Cargo

Calendula CLI can be installed with cargo:

cargo install calendula

With only Vdir support:

cargo install calendula --no-default-features --features vdir

You can also use the git repository for a more up-to-date (but less stable) version:

cargo install --locked --git https://github.com/pimalaya/calendula.git

Nix

Calendula CLI can be installed with Nix:

nix-env -i calendula

You can also use the git repository for a more up-to-date (but less stable) version:

nix-env -if https://github.com/pimalaya/calendula/archive/master.tar.gz

Or, from within the source tree checkout:

nix-env -if .

If you have the Flakes feature enabled:

nix profile install calendula

Or, from within the source tree checkout:

nix profile install

You can also run Calendula directly without installing it:

nix run calendula

Configuration

The wizard is not yet available (it should come soon, see #7), so the only way to configure Calendula CLI is to copy the sample config file, to store it either at ~/.config/calendula.toml or ~/.calendularc then to customize it by commenting or uncommenting the options you need.

Google

Google Calendar requires OAuth 2.0. The first step is to configure an OAuth 2.0 token manager like Ortie, with the calendar scope https://www.googleapis.com/auth/calendar:

caldav.auth.bearer.command = ["ortie", "token", "show"]

Google Calendar does not propose discovery service, nor server URI. You need to directly use the following home URI:

caldav.home-uri = "https://apidata.googleusercontent.com/caldav/v2/your.email@gmail.com"

Apple

Apple Calendars does not propose discovery service. The only way is to use their server URI combined with basic authentication:

caldav.server-uri = "https://calendars.icloud.com"
caldav.auth.basic.username = "your.email@icloud.com"
caldav.auth.basic.password.raw = "your.password"

If you check attentively the --trace logs, you should see the home URI. It is not recommended to use it directly, but it can make the CLI definitely faster. It should look like this:

caldav.home-uri = "https://p156-caldav.icloud.com:443/17170244959/calendars/"

Microsoft

Microsoft only proposes a proprietary, non-standard API.

Posteo

Posteo proposes a discovery service, combined with basic authentication:

caldav.discover.host = "posteo.de"
caldav.auth.basic.username = "your.email"
caldav.auth.basic.password.raw = "your.password"

Discovery is the recommended way to go, but it is slow. If you want faster calls you can "hardcode" the server URI and/or the home URI, at your own risk:

caldav.server-uri = "https://posteo.de:8843"
caldav.home-uri = "https://posteo.de:8843/calendars/your.email/"

FAQ

Sponsoring

Special thanks to the NLnet foundation and the European Commission that helped the project to receive financial support from various programs:

• NGI Assure in 2022
• NGI Zero Entrust in 2023
• NGI Zero Core in 2024 (still ongoing)

If you appreciate the project, feel free to donate using one of the following providers: