✓ Verified 💻 Development ✓ Enhanced Data

Icloud Caldav

Direct iCloud Calendar integration via CalDAV protocol.

Rating: 4 (259 reviews)
Downloads: 3,161 downloads
Version: 1.0.0

Overview

Direct iCloud Calendar integration via CalDAV protocol.

Complete Documentation

View Source →

iCloud CalDAV — Direct Calendar Access

Manage iCloud Calendar directly via CalDAV protocol. No third-party services, no data leaves your machine except to Apple's servers.

When to Use

Activate when the user wants to:

Check their calendar or upcoming events
Create new calendar events
Delete existing events
List available calendars

Do NOT use for:

Reminders (use apple-reminders skill if available)
Contacts (CalDAV is calendar-only)
Non-iCloud calendars (Google, Outlook, etc.)

Prerequisites

Required credentials:

APPLE_ID — Your Apple ID email address
APPLE_APP_PASSWORD — An app-specific password (NOT your regular Apple ID password)

To generate app-specific password:

Go to appleid.apple.com
Sign in → Sign-In and Security → App-Specific Passwords
Generate a new password
Use this password (not your regular one)

Quick Start

bash

# Set credentials
export APPLE_ID="[email protected]"
export APPLE_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"

# List calendars
./scripts/caldav.py list-calendars

# List events for next 7 days
./scripts/caldav.py list-events --days 7

# Create an event
./scripts/caldav.py create-event \
  --title "Team Meeting" \
  --start "2025-07-23T14:00:00" \
  --duration 60 \
  --calendar "Work"

Available Operations

Operation	Command	Description
List calendars	list-calendars	Show all iCloud calendars
List events	list-events	Events in a date range
Create event	create-event	Add new calendar event
Delete event	delete-event	Remove event by filename or UID

Workflow Patterns

Creating Events

bash

# Basic event
./scripts/caldav.py create-event \
  --title "Dentist Appointment" \
  --start "2025-07-25T09:30:00" \
  --duration 30

# With location and description
./scripts/caldav.py create-event \
  --title "Project Review" \
  --start "2025-07-26T14:00:00" \
  --duration 60 \
  --location "Conference Room B" \
  --description "Q3 planning review" \
  --calendar "Work"

# All-day event
./scripts/caldav.py create-event \
  --title "Vacation" \
  --start "2025-08-01" \
  --all-day

Batch Operations

Note: CalDAV does not support native batch operations. To create multiple events, run the script multiple times:

bash

# Create multiple events by running the command multiple times
./scripts/caldav.py create-event --title "Meeting 1" --start "2025-07-26T10:00:00" --duration 60
./scripts/caldav.py create-event --title "Meeting 2" --start "2025-07-26T14:00:00" --duration 60
./scripts/caldav.py create-event --title "Meeting 3" --start "2025-07-27T09:00:00" --duration 60

iCloud handles rapid sequential requests well, but there is no single API call for creating multiple events.

Deleting Events

bash

# Delete by filename
./scripts/caldav.py delete-event \
  --file "event-name.ics" \
  --calendar "Calendar"

# Delete by UID (searches calendar for matching event)
./scripts/caldav.py delete-event \
  --uid "[email protected]" \
  --calendar "Calendar"

Warning: Deletions are permanent. iCloud may have its own backup, but standard CalDAV DELETE immediately removes the event.

Date/Time Formats

ISO 8601: 2025-07-23T14:00:00 (assumes local timezone if none specified)
With timezone: 2025-07-23T14:00:00+08:00
All-day: 2025-07-23 (date only)

Security Notes

Credentials are read from environment variables only
No credentials are logged or stored
All communication is HTTPS to caldav.icloud.com
App-specific passwords can be revoked anytime at appleid.apple.com

Error Handling

Error	Cause	Solution
401 Unauthorized	Bad credentials	Check APPLE_ID and APPLE_APP_PASSWORD
404 Not Found	Calendar/event doesn't exist	List calendars/events first
403 Forbidden	Read-only calendar	Try a different calendar
Timeout	Network issue	Retry the request

References

See references/caldav-protocol.md for CalDAV implementation details
See references/icloud-endpoints.md for iCloud-specific endpoints

Installation

Terminal bash


openclaw install icloud-caldav

Copied!

💻Code Examples

--calendar "Work"

---calendar-work.txt

## Available Operations

| Operation | Command | Description |
|-----------|---------|-------------|
| List calendars | `list-calendars` | Show all iCloud calendars |
| List events | `list-events` | Events in a date range |
| Create event | `create-event` | Add new calendar event |
| Delete event | `delete-event` | Remove event by filename or UID |

## Workflow Patterns

### Creating Events

--all-day

---all-day.txt

### Batch Operations

**Note:** CalDAV does not support native batch operations. To create multiple events, run the script multiple times:

./scripts/caldav.py create-event --title "Meeting 3" --start "2025-07-27T09:00:00" --duration 60

scriptscaldavpy-create-event---title-meeting-3---start-2025-07-27t090000---duration-60.txt

iCloud handles rapid sequential requests well, but there is no single API call for creating multiple events.

### Deleting Events

example.sh

# Set credentials
export APPLE_ID="[email protected]"
export APPLE_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"

# List calendars
./scripts/caldav.py list-calendars

# List events for next 7 days
./scripts/caldav.py list-events --days 7

# Create an event
./scripts/caldav.py create-event \
  --title "Team Meeting" \
  --start "2025-07-23T14:00:00" \
  --duration 60 \
  --calendar "Work"

example.sh

# Basic event
./scripts/caldav.py create-event \
  --title "Dentist Appointment" \
  --start "2025-07-25T09:30:00" \
  --duration 30

# With location and description
./scripts/caldav.py create-event \
  --title "Project Review" \
  --start "2025-07-26T14:00:00" \
  --duration 60 \
  --location "Conference Room B" \
  --description "Q3 planning review" \
  --calendar "Work"

# All-day event
./scripts/caldav.py create-event \
  --title "Vacation" \
  --start "2025-08-01" \
  --all-day

example.sh

# Create multiple events by running the command multiple times
./scripts/caldav.py create-event --title "Meeting 1" --start "2025-07-26T10:00:00" --duration 60
./scripts/caldav.py create-event --title "Meeting 2" --start "2025-07-26T14:00:00" --duration 60
./scripts/caldav.py create-event --title "Meeting 3" --start "2025-07-27T09:00:00" --duration 60

example.sh

# Delete by filename
./scripts/caldav.py delete-event \
  --file "event-name.ics" \
  --calendar "Calendar"

# Delete by UID (searches calendar for matching event)
./scripts/caldav.py delete-event \
  --uid "[email protected]" \
  --calendar "Calendar"