icloud-caldav

name	icloud-caldav
description	Direct iCloud Calendar integration via CalDAV protocol. Create, read, update, and delete calendar events without third-party services. Use when the user wants to manage their iCloud Calendar, check schedule, create events, or find free time. Requires Apple ID and app-specific password.

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:

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

Quick Start

# Set credentials
export APPLE_ID="[e-mail]"
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

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

# 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

# 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 "[e-mail]" \
  --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