export ICLOUD_USERNAME="user@icloud.com"
export ICLOUD_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
python -m icalendar_sync setup --non-interactive

Use file storage only when keyring is unavailable (headless or GUI-restricted runtime):

python -m icalendar_sync setup --non-interactive --storage file --config ~/.openclaw/icalendar-sync.yaml

2. Choose Provider Deliberately

--provider auto: macOS uses native bridge, non-macOS uses CalDAV.
--provider caldav: force direct iCloud CalDAV.
--provider macos-native: force Calendar.app bridge (macOS only).

For CalDAV diagnostics, add:

--debug-http --user-agent "your-agent/1.0"

3. Execute Calendar Operations

List calendars:

python -m icalendar_sync list

Get events:

python -m icalendar_sync get --calendar "Personal" --days 7

Create event:

python -m icalendar_sync create --calendar "Personal" --json '{
  "summary": "Meeting",
  "dtstart": "2026-02-15T14:00:00+03:00",
  "dtend": "2026-02-15T15:00:00+03:00"
}'

Update event (simple):

python -m icalendar_sync update --calendar "Personal" --uid "event-uid" --json '{"summary":"Updated title"}'

Update recurring event instance:

python -m icalendar_sync update \
  --calendar "Work" \
  --uid "series-uid" \
  --recurrence-id "2026-03-01T09:00:00+03:00" \
  --mode single \
  --json '{"summary":"One-off change"}'

Modes for recurring updates:

single: update one instance (use --recurrence-id)
all: update whole series
future: split series and update this+future (use --recurrence-id)

Delete event:

python -m icalendar_sync delete --calendar "Personal" --uid "event-uid"

4. Input Contract

For create, require at least:

summary (string)
dtstart (ISO datetime)
dtend (ISO datetime, must be later than dtstart)

Optional fields:

description
location
status
priority (0-9)
alarms
rrule

5. Safety Rules

Validate calendar names; reject path-like payloads.
Keep credential material out of logs/output.
Prefer keyring over file storage.
If file storage is used, enforce strict file permissions (0600).

6. Failure Handling

If CalDAV auth/network fails on macOS and provider is auto/caldav, switch to macos-native and retry the same operation.

If JSON payload is supplied as file path, ensure file size stays within safe limits before parsing.

icalendar-sync

iCalendar Sync

1. Prepare Credentials Securely