icalendar-sync
# 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.
标签
skill
ai
