Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Settings

First start

If the config file doesn’t exist when the app starts, or holds nothing but blank lines and comments, the app writes the starter config there (creating the directory, keeping existing comments below it) and logs “starter config written”. Every setting in it is commented out, so the app greets you with a small “Welcome to Capycal” window (once per start): it asks whether your calendars are in Calendar.app or in a CalDAV account (and adds the account), then for the source, the target (in another account added right there, if need be) and what to copy, one question at a time, with dots showing the step and Cancel, Back and Continue at the bottom (Return continues, Escape cancels). At the end it says the sync runs; Open Settings shows the full editor, Done closes the window. Sync Now stays disabled until there is one.

The window

Settings… opens a window (as large as you left it, on the entry you looked at last) with your syncs and accounts on the left (a disabled sync has a grey icon, one whose last sync failed an orange one) and the selected one on the right. Add Sync… below the syncs and Add Account… below the accounts add one. At the bottom of the sidebar is the version of Capycal. Under a sync’s name, a line says how it is doing: “Synced 2 min ago: 3 new, 1 removed”, “Syncing now…”, or why the last sync failed. The bar at the bottom says when there are unsaved changes and holds Revert and Save; a dot after the entry’s name in the list marks them too. Cmd+S saves, Cmd+N adds a sync and Cmd+Delete deletes the entry shown (on Linux with Ctrl).

Add Sync… starts the same assistant in a small window over Settings (a sheet on macOS), with one question per step: the source calendar, the target calendar (the source and calendars you may only read are greyed out) what the copies show: Busy blocker (only the time, titled “Busy (Work)” after the source calendar), Title and time, Everything (title, notes, location and reminders), each card with a preview of a copied event, or Custom, and last its name, proposed as work-to-blockers. Create saves the sync and shows it in the editor below, where you can change everything. A Custom sync starts switched off (enabled = false), so it copies nothing until you set it up and switch it on. Cancel (or closing it) returns to Settings as it was. Set Up in Editor leaves the assistant for the editor with what you picked so far, for those who rather fill in the form. A right click on a sync in the list offers Duplicate: a new, unsaved copy named <sync>-copy. Calendar.app’s calendars are listed under their account (iCloud, Exchange, …), accounts and calendars in alphabetical order. A calendar in a CalDAV account that is not set up yet: Add Another Account… (Add CalDAV Account… while there is none) below the calendars of the source or target step adds the account in the assistant and comes back to that step with its calendars, for example a second server for the target of a CalDAV to CalDAV sync, or a CalDAV target for a Calendar.app source. Add Account… in the sidebar adds one outside the assistant. Add Calendar Feed… below the calendars of the first step shows a Feed address field: paste a calendar’s iCal address there to copy from it.

A sync shows its name at the top (click it to rename; Esc or a click beside it ends editing) with its on/off switch at the right (off is enabled = false: configured but stopped), and below a sentence saying what it does, such as “Copies events from Calendar into Family every 5 min.” The step you work in is outlined in the accent color. Below, the sync is drawn as the steps an event takes, from top to bottom:

  • From: the source calendar and how often it is checked (Check every: 1, 5 or 15 minutes, or Custom for any other, such as 10m or 2h). The calendar menus list the calendars of every account, found on the server when the window opens, and the calendars of Calendar.app. Without a connection they show the error and the calendars already in the config; Refresh next to them asks the servers again. Add Calendar Feed… at the end of the menu reads a calendar from its iCal address instead, such as Google’s secret address: paste it into Feed address below, and the feed is named after the site (“google”). Feeds you added are listed under Feeds, and Feed address shows and changes the address of the one chosen; an address set in the config file through env, file, command or keychain is not shown. See Calendar feeds.
  • Keep: the content copied on top of times, recurrence, status and free/busy: Only the time, Title, Title, notes, location, reminders, or Custom, which shows the fields as checkboxes and others (such as X-CUSTOM) as text.
  • One step per transform, in the order they run, each numbered and as a sentence (“Set SUMMARY to “Busy”“). Click one to edit its fields in it (Field suggests common iCal fields such as LOCATION and takes any other name too, always in upper case) and its conditions: Add Condition adds one, which reads Only if (If for Skip events, which starts with one and keeps at least one) and then if, with what it looks at (Title, Location, Notes, Other field, Start with one checkbox per weekday and From / Until, Event for all-day), its test and its text, arrows to move it up or down, Remove, and a handle (≡) to drag it to another place; the and / or switch between two conditions says whether both have to match or one is enough, and conditions joined by or share a box, One of these (a condition dropped inside it joins it, one dropped right above or below it stays out) (see Conditions); drag it by its handle (≡) to another place, the bin removes it. The + between two steps adds a transform right there, each named with a line saying what it does; below the transforms its menu offers Common steps that come filled in: hide the details (title “Busy”), travel time (30 min before and after), travel time only for events with a location, skip weekends, skip outside working hours (Mon-Fri before 8:00 and from 18:00) and a reminder 10 min before. Cmd+Z undoes adding, moving or removing a step. Without a mouse, a right click on a step (VoiceOver: its context menu) offers Move Up, Move Down and Remove, and Cmd+Option+Up / Down moves the open step (on Linux Ctrl+Alt). A field with a mistake (an invalid regex, a time like 25:00) shows it below the field once you leave it, not while you type. While something keeps Save disabled, the bar at the bottom says what, with a warning sign, for example “Set field (step 1): fill in Field and Value”.
  • Into: the target calendar. A calendar the account may only read, and a feed, is greyed out.
  • Advanced settings below: how often a full sync runs (Full sync every), the window of days read from a Calendar.app source, Parallel writes of a CalDAV target (concurrency of the target calendar, default 2, shared by every sync writing into it), and, for a saved sync, Troubleshooting: Full Sync Now compares all copies with the source and fixes the ones that differ (the status line says “Full sync running…” meanwhile, and the bar at the bottom shows how far it got, as it does for the full sync that follows a save), Remove Synced Events… removes this sync’s copies from the target, after asking, and switches the sync off, Remove All Events… empties the target calendar (see below).

Right of the steps, One event on its way shows a sample meeting (Tuesday 9:00 to 10:00, with a place, notes and a reminder) and the copy this sync would make of it, through the same fields and transforms the sync uses; it follows every change before you save. Next event above it reads the source’s next event and shows that one instead of the sample (again each time you choose it). Picking a calendar that is not in the config yet adds a [calendars.<name>] entry for it when you save; a calendar no sync uses any more is removed after asking. Advanced settings below the steps hold the full sync interval and, for a Calendar.app source, Calendar.app events: the days back and ahead the sync reads; with All events these do not apply and are greyed out.

Save writes the config, keeping your comments and the order of everything else, and the syncs restart with it. Renaming a sync or changing its target first removes the events it copied into the old target, after asking, and then copies the source again; otherwise the old copies would stay behind without a sync that owns them. Changing what a sync copies (source, fields, transforms) makes its next cycle a full sync, so the copies already made get the new content. Delete (at the bottom left) removes a sync together with its copies, or with Keep Copies leaves them in the target. While copies are removed, the bar at the bottom counts them (“Removing the synced events of "work-to-home"… 120 of 340”) next to a progress bar.

An account has a name, the server URL, the user name and the password. A password you type is stored in the Keychain (service app.capycal, the account’s name) and the config only says password = { keychain = "<name>" }. A password from an environment variable, a file or a command stays as it is until you type a new one. When macOS would ask before Capycal reads a Keychain password (after an update to a build with a new signature), the app first says why and which accounts it reads, and starts the syncs once you close that note; choose Always Allow in the macOS prompt so it does not come back. Test Connection looks up the account’s calendars with what you entered. Below the box, the page lists the syncs that use the account; Delete removes it once none does.

If the config file changes while you have unsaved changes to the same sync or account, a yellow Changed on disk banner offers Reload (drop your changes) or Overwrite (keep them; Save writes them). Without unsaved changes the window just shows the new state. Closing the window or choosing another entry with unsaved changes asks first.

What each setting does, with its key in the config: Calendars and accounts, Syncs, Transforms, Full sync.

General

General at the top of the list holds the app’s own settings: Start Capycal at login, the Log level (written as [daemon] log_level; a filter written by hand shows as “Custom”) with Show Log, and the Config file with Open in Editor… and Show in Finder. When something keeps the config from running, General turns orange and starts with Needs attention: the mistake in the config file (where it is and what is wrong) with Open in Editor…, another Capycal process holding the config with Reload Config, or a failed removal of synced events with Show Log. Settings also opens when the config file cannot be read at all, then with only General, and shows everything once the file is fixed. Open in Editor… writes the starter config if the file is missing and opens it in the app for .toml files, or in the default text editor. Saving it reloads the syncs. Settings and your own edits can be mixed: Settings keeps your comments and only replaces the entries it changes. To find calendar URLs and identifiers for hand-written entries, use capycal --discover and capycal --discover-eventkit (see CLI reference).