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 ic...

# iCalendar Sync for OpenClaw

Secure iCloud Calendar integration for OpenClaw agents.

[![Version](https://img.shields.io/badge/version-2.4-blue.svg)](https://github.com/h8kxrfp68z-lgtm/iCalendar-Sync/releases)
[![Security](https://img.shields.io/badge/security-A-brightgreen.svg)](SECURITY.md)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)

## What It Does

- List calendars
- Get events by time window
- Create events (including alarms and RRULE)
- Update events
- Update recurring events in modes: `single`, `all`, `future`
- Delete events
- Store credentials in OS keyring or secure YAML file (`0600`)
- Smart provider behavior in `auto` mode (tries CalDAV first, falls back to `macos-native` on macOS)
- Explicit provider enforcement (`--provider caldav` will not silently switch to native)
- Optional keyring bypass for debugging (`--ignore-keyring`)

## Requirements

- Python 3.9+
- iCloud App-Specific Password (not Apple ID primary password)
- Network access to iCloud CalDAV for `caldav` provider
- macOS only for `macos-native` provider (AppleScript bridge to Calendar.app)

## Installation

From source:

```bash
git clone https://github.com/h8kxrfp68z-lgtm/iCalendar-Sync.git
cd iCalendar-Sync
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
```

With dev dependencies:

```bash
pip install -e '.[dev]'
```

## Quick Start

### 1. Configure credentials

Interactive (recommended for local usage):

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

Headless / automation:

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

If keyring is unavailable:

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

### 2. Run commands

```ba...