iCloud Toolkit

Calendar + Email + Contacts CLI. One script, all iCloud operations.

Script: scripts/icloud.py | Config: config/config.json

Rules

• Always use the CLI commands below instead of reading source files, parsing .ics/.vcf files directly, or grepping code. The CLI handles CalDAV discovery, IMAP operations, feed fetching, sync, timezone conversion, and formatting internally.
• One query first, fan out only if needed. Start with a single calendar list --days N or calendar search "<keyword>" — scan the output yourself before running more commands. Do not run multiple searches with different keywords in parallel. Each command triggers a sync cycle, so fewer calls = faster answers.
• For multi-calendar queries (e.g., "when are we both free?"), run calendar list for each calendar separately, then reason over the combined output.
• Subscribed calendars are read-only. You can list and search them, but calendar create and calendar delete only work on owned calendars.
• Run calendar refresh if the user mentions subscribing to a new calendar.
• If a calendar returns no events, report that to the user — don't debug it. Empty results are valid. The user may not have events, or the calendar may need a calendar refresh. Never write scripts to parse data or call APIs as a workaround.
• Always ask permission before sending or deleting emails on behalf of the user.
• Don't re-read this file every turn. Once you've read SKILL.md in a session, you have the commands — just use them.

Quick reference

ICLOUD=~/.openclaw/workspace/skills/icloud-toolkit/scripts/icloud.py

# Calendar
python3 $ICLOUD calendar list                                    # Today
python3 $ICLOUD calendar list --days 7                           # Next 7 days
python3 $ICLOUD calendar list --days 7 --calendar Appointments   # Specific calendar
python3 $ICLOUD calendar search "meeting"                        # Search events
python3 $ICLOUD calendar create <cal> <date> <start> <end> <title> [--location X] [--description X]
python3 $ICLOUD calendar create-allday <cal> <date> <title> [--description X]
python3 $ICLOUD calendar delete <uid>
python3 $ICLOUD calendar sync                                    # Manual sync
python3 $ICLOUD calendar disable <name>                          # Hide from listings
python3 $ICLOUD calendar enable <name>                           # Show in listings
python3 $ICLOUD calendar refresh                                 # Re-discover calendars