iCalendar Sync

Use this skill to perform iCloud calendar CRUD operations from OpenClaw agents.

1. Prepare Credentials Securely

Use App-Specific Passwords only (never the primary Apple ID password).

Prefer keyring storage:

python -m icalendar_sync setup --username user@icloud.com

Use non-interactive setup for automation:

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.