Command reference
oko calendar sync
Syncs every connected account (or one) over the window the caller names into the device-local events mirror.
Invocation#
oko calendar sync --days-past N --days-ahead N [--account ID]Inputs and options#
- --days-past and --days-ahead are required whole numbers of days back and ahead of now; Oko assumes no window. Oko Desktop's Calendar screen keeps the two as Sync days back and Sync days ahead and passes them on Sync now.
- --account narrows the sync to one connected account.
Output and state effect#
- Fetches each account's window — Google and Microsoft expand recurrences server-side, CalDAV/ICS carry the raw RRULE — and replaces that account's slice of ~/.oko/calendar/events.json, so cancelled events disappear.
- Every HTTP request for a connected account — sync, add, edit and remove alike — is made by oko calendar request --account ID --method M --url U [--header NAME=VALUE]… [--body], which prints the answer's status and body. Google and Microsoft requests only go to the provider's own API address. An access token that ends within a minute is first refreshed at the provider's token endpoint with the account's client id, client secret and refresh token, read inline or from its Skarbiec item; the new access token and expiry are written back to accounts.json, and a refresh token the provider rotated goes back where it came from — the account file for an inline one, the Skarbiec item for a vault-backed one — so no secret is ever copied into the file. CalDAV and ICS requests carry Basic credentials from the account or its item and only go to the server of the account's own URL; any other address is refused by name.
- A failing account never aborts the others; its error rides in the summary and the run exits unsuccessfully.
- When a Wisent member is signed in on this machine the records also mirror, through oko with their session, into their organization's calendar_events table and events gone from the window are pruned there; OKO_CALENDAR_NO_MIRROR=1 keeps a run device-local, and without a signed-in member the mirror is skipped.
Refusals and safe exits#
- Without the window: “calendar sync needs its window: --days-past N and --days-ahead N (native: days_past, days_ahead)”; a negative count: “calendar sync day counts must be nonnegative”.
- With no connected accounts it refuses: no calendar accounts are connected; run 'oko calendar connect {eventkit|google|microsoft|caldav|ics} ...' first.
- A non-ICS payload, refused credentials (HTTP 401), and an unreachable server each fail with their exact sentence naming the URL.
- A refused refresh fails with the provider's token endpoint answer — “Google Calendar token endpoint answered HTTP 400: …” — and an account with neither an access token nor a refresh token refuses with “the account holds no access token and nothing to refresh one with”.
- An event the account cannot be mirrored from fails that account's sync naming it, instead of being dropped or stored under an invented id: an ICS event without a UID (“a VEVENT carries no UID, which RFC 5545 requires”), without or with an unreadable DTSTART, with an unreadable DTEND, or whose length is given only as DURATION (“event … states its length as DURATION …, which this reader does not read”); a Google or Microsoft event without an id or with a start or end that does not read. A missing DTEND keeps the RFC 5545 default: a whole day for a date, no length for a date-time.