Sync Icloud Calendar Via Caldav

---
name: sync-icloud-calendar-via-caldav
description: "Secure iCloud Calendar operations for OpenClaw with CalDAV and macOS native bridge providers. Use when tasks require calendar listing, event retrieval, event creation, event updates (including recurring series modes), event deletion, or credential setup via keyring/environment/c…"
category: "Productivity"
author: community
version: "2.4.1"
icon: check-square
---

# 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:

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

Use non-interactive setup for automation:

```bash
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):

```bash
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:

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

## 3. Execute Calendar Operations

List calendars:

```bash
python -m icalendar_sync list
```

Get events:

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

Create event:

```bash
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):

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

Update recurring event instance:

```bash
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:

```bash
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.