iCalendar Sync

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

Prefer keyring storage:

```bash
python -m icalendar_sync setup --username [email protected]
```

Use non-interactive setup for automation:

```bash
export ICLOUD_USERNAME="[email protected]"
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.