🔔 carillon

CLI to watch PIM collection changes, written in Rust

[!CAUTION] Carillon is v0.x: expect breaking changes between releases until it stabilises.

Features

Mail backend support: IMAP ^rfc2177, JMAP ^rfc8621, Maildir ^specs
Calendars and contacts backend support: CalDAV, CardDAV ^rfc6578, JMAP ^{rfc9610, calendars}
Alarms of events and tasks ^rfc5545, fired from a CalDAV calendar or a local pimdir store, no sync needed for the former
Vendor API support: Microsoft Graph (mail, contacts, calendar), Gmail, Google Calendar, Google People
Watch support: IMAP idle, JMAP event stream, collection poll everywhere else
Hook support: desktop notification, shell command, or both, on every change
Simple auth support for IMAP: anonymous, login, plain, oauthbearer, xoauth2, scram-sha-256
HTTP auth support for JMAP (basic, bearer, raw header), DAV (basic, bearer) and the vendor APIs (bearer)
TLS support:
- Rustls with ring crypto (requires rustls-ring feature, enabled by default)
- Rustls with aws crypto (requires rustls-aws feature)
- Native TLS (requires native-tls feature)
Discovery support:
- PACC ^specs
- Autoconfiguration (Thunderbird) ^specs
- SRV DNS lookups ^rfc6186
- DAV service discovery ^rfc6764
- JMAP session ^rfc8620
Multi-account watch: every configured account at once, each reconnecting on its own
Interactive wizard: carillon configure turns an email address into a tested account

[!TIP] Carillon is written in Rust and uses cargo features to gate backend support. The default feature set is declared in Cargo.toml.

The default wizard feature brings the interactive configure; leave it out of a scripted or embedded build that never prompts.

Installation

Pre-built binary

As root:

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

As a regular user:

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

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

For a more up-to-date version, check the releases workflow and look for the Artifacts section: those are built from master, with the default cargo features.

Cargo

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

With IMAP support only, which drops every other backend:

cargo install --locked --git https://github.com/pimalaya/carillon.git \
  --no-default-features \
  --features imap,rustls-ring

Nix

If you have the Flakes feature enabled:

nix profile install github:pimalaya/carillon

Or run without installing:

nix run github:pimalaya/carillon

Sources

git clone https://github.com/pimalaya/carillon
cd carillon
nix run

Configuration

The configuration is loaded from the first existing path among:

$XDG_CONFIG_HOME/carillon/config.toml
$HOME/.config/carillon/config.toml
$HOME/.carillonrc

Override the path with carillon -c <PATH> or CARILLON_CONFIG=<PATH>. Multiple paths can be passed at once, separated by :; the first is the base and the rest are deep-merged on top. The full field reference lives in config.sample.toml.

Run carillon with no command to launch the wizard, carillon configure to run it again later. It discovers the services your provider publishes from your email address, offering the Microsoft Graph or Google APIs first for such an account, asks which one to watch and how to authenticate, then tests the connection.

The watch method is never asked: an account takes the best one its backend supports. The result is saved, appended to the configuration already there, or printed for you to place by hand.

An account declares one backend block (imap, jmap, maildir, caldav, carddav, msgraph, gmail, gcal, gpeople, pimdir) carrying the collection it watches (one per domain over JMAP and Microsoft Graph, sharing one connection), how it watches it (watch) and what it fires (hook). Declaring several is allowed, -b/--backend then selecting one.

Usage

Generate an account:

carillon configure

Watch every configured account, until interrupted:

carillon watch

Watch one account:

carillon -a work watch

Check that an account still connects and authenticates, on every backend it declares, before trusting a watch to keep running:

carillon -a work check

Force a backend on an account declaring several:

carillon -b jmap watch

Every command and every flag is documented behind --help. Man pages, shell completions and the JSON Schemas of the --json output are generated by carillon manual --dir <DIR>, carillon completion --dir <DIR> and carillon json-schema --dir <DIR>.

Logs go to stderr, so they can be redirected to a file while the command output stays on stdout:

carillon watch --log-level debug 2>/tmp/carillon.log

Use --log-file <PATH> to append them to a file directly. When --log-level is omitted the RUST_LOG environment variable is consulted, and RUST_BACKTRACE=1 adds the full error backtrace.