Command-line and Emacs Calendar Client
ryan.freumh.org
1# Caledonia
2
3Caledonia is a calendar client with command-line and Emacs front-ends.
4It operates on a [vdir](https://pimutils.org/specs/vdir/) directory of [`.ics`](https://datatracker.ietf.org/doc/html/rfc5545) files as managed by tools like [vdirsyncer](https://github.com/pimutils/vdirsyncer), which allows it to interact with CalDAV servers.
5
6The command-line has the `list`, `search`, `show`, `add`, `delete`, and `edit` subcommands, and has full timezone support.
7
8An example `list` invocation is,
9
10```
11$ caled list
12personal 2025-04-04 Fri 13:00 - 14:00 (America/New_York) New York 8am meeting 054bb346-b24f-49f4-80ab-fcb6040c19a7
13family 2025-04-06 Sun 21:00 - 22:00 (UTC) Family chat @Video call 3B84B125-6EFC-4E1C-B35A-97EFCA61110E
14work 2025-04-09 Wed 15:00 - 16:00 (Europe/London) Weekly Meeting 4adcb98dfc1848601e38c2ea55edf71fab786c674d7b72d4c263053b23560a8d
15personal 2025-04-10 Thu 11:00 - 12:00 (UTC) Dentist ccef66cd4d1e87ae7319097f027f8322de67f758
16family 2025-04-13 Sun 21:00 - 22:00 (UTC) Family chat @Video call 3B84B125-6EFC-4E1C-B35A-97EFCA61110E
17personal 2025-04-15 Tue - 2025-04-17 Thu John Doe in town 33cf18ec-90d3-40f8-8335-f338fbdb395b
18personal 2025-04-15 Tue 21:00 - 21:30 (UTC) Grandma call 8601c255-65fc-4bc9-baa9-465dd7b4cd7d
19work 2025-04-16 Wed 15:00 - 16:00 (Europe/London) Weekly Meeting 4adcb98dfc1848601e38c2ea55edf71fab786c674d7b72d4c263053b23560a8d
20personal 2025-04-19 Sat Jane Doe's birthday 7hm4laoadevr1ene8o876f2576@google.com
21family 2025-04-20 Sun 21:00 - 22:00 (UTC) Family chat @Video call 3B84B125-6EFC-4E1C-B35A-97EFCA61110E
22personal 2025-04-22 Tue 21:00 - 21:30 (UTC) Grandma call 8601c255-65fc-4bc9-baa9-465dd7b4cd7d
23work 2025-04-23 Wed 15:00 - 16:00 (Europe/London) Weekly Meeting 4adcb98dfc1848601e38c2ea55edf71fab786c674d7b72d4c263053b23560a8d
24family 2025-04-27 Sun 21:00 - 22:00 (UTC) Family chat @Video call 3B84B125-6EFC-4E1C-B35A-97EFCA61110E
25personal 2025-04-29 Tue 21:00 - 21:30 (UTC) Grandma call 8601c255-65fc-4bc9-baa9-465dd7b4cd7d
26work 2025-04-30 Wed 15:00 - 16:00 (Europe/London) Weekly Meeting 4adcb98dfc1848601e38c2ea55edf71fab786c674d7b72d4c263053b23560a8d
27```
28
29The Emacs client is defined in [./emacs](./emacs) and communicates with `caled server` using a [S-expression](https://en.wikipedia.org/wiki/S-expression) based protocol.
30
31See [TODO](./TODO.org) for future plans.
32
33## Installation
34
35With [opam](https://opam.ocaml.org/),
36
37```
38$ opam install .
39```
40
41With [Nix](https://nixos.org/),
42
43```
44$ nix shell 'git+https://tangled.sh/@ryan.freumh.org/caledonia?ref=main'
45```
46
47## Configuration
48
49Caledonia looks for calendars in the directory specified by the `CALENDAR_DIR` environment variable or in `~/.calendars/` by default.
50
51## Tests
52
53The project includes a test suite that can be ran with `dune runtest`.
54
55## Thanks
56
57To [Patrick](https://patrick.sirref.org/) for suggesting the name, and all the developers of the dependencies used, especially [icalendar](https://github.com/robur-coop/icalendar) and [timere](https://github.com/daypack-dev/timere).
58