🔔 carillon

CLI to watch PIM collection changes, written in Rust

• Features
• Installation
• Configuration
• Usage
• AI policy
• License
• Social
• Contributing
• Sponsoring

• Mail backend support: IMAP ^rfc2177, JMAP ^rfc8621, Maildir ^specs
• Calendars and contacts backend support: CalDAV, CardDAV ^rfc6578
• 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) and DAV (basic, 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

Not released yet. Until it is, the releases workflow builds one from master on demand, under Artifacts, with the default cargo features.

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

With IMAP support only, which drops the JMAP, Maildir and WebDAV backends:

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

If you have the Flakes feature enabled:

nix profile install github:pimalaya/carillon

Or run without installing:

nix run github:pimalaya/carillon

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

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, 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) carrying the collection it watches, how it watches it (watch) and what it fires (hook). Declaring several is allowed, -b/--backend then selecting one.

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.

This project is licensed under either of:

• MIT license
• Apache License, Version 2.0

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022 → 2023: NGI Assure
• 2023 → 2024: NGI Zero Entrust
• 2024 → 2026: NGI Zero Core
• 2026 → 2027: NGI Zero Commons Fund

This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider sponsoring its development: