iCloud Calendar CLI: Manage Events

How do you use an iCloud Calendar CLI from terminal?

Connect iCloud once, then run nylas calendar events list, nylas calendar events create, and nylas calendar availability find. This gives you an iCloud Calendar CLI workflow without CalDAV endpoint setup, app-specific passwords, or XML parsing.

Apple's missing calendar API is the reason iCloud Calendar automation usually starts with CalDAV.

Apple does not provide a REST API, CLI, or SDK for iCloud Calendar. The only programmatic access path is CalDAV (RFC 4791), a protocol that requires app-specific passwords, XML parsing, and manual server discovery. According to Apple's developer documentation, CalDAV at caldav.icloud.com is the sole integration point for third-party calendar tools.

Google has the Calendar API. Microsoft has Graph API. Apple has CalDAV and nothing else. CalDAV works, but the setup takes 5 steps before you can read a single event:

1. Enable two-factor authentication on your Apple ID (mandatory since March 2023)
2. Generate an app-specific password at appleid.apple.com
3. Configure your CalDAV client with caldav.icloud.com on port 443
4. Discover calendar home URLs through PROPFIND requests
5. Parse XML responses for every operation

App-specific passwords can't be refreshed programmatically. If your Apple ID password changes, all app-specific passwords get revoked. Apple limits each Apple ID to 25 app-specific passwords at a time, and revoking one invalidates only that password — but a full Apple ID password reset revokes all 25. For automation, that's a dead end.

1. Install the Nylas CLI

The Nylas CLI installs in under 30 seconds on macOS, Linux, and Windows. It connects to iCloud Calendar through Nylas's CalDAV connector, so you skip the manual endpoint configuration at caldav.icloud.com entirely. The CLI binary is a single Go executable under 50 MB with no runtime dependencies.

Run brew install nylas/nylas-cli/nylas on macOS or Linux. For Windows PowerShell or alternative install methods, see the getting started guide.

2. Authenticate your iCloud account

Nylas CLI authentication replaces Apple's app-specific password flow with a single API key. Instead of generating passwords at appleid.apple.com and configuring CalDAV endpoints manually, you paste one key and the CLI handles token management, including automatic refresh. The entire setup takes about 2 minutes.

Create an application at dashboard-v3.nylas.com, connect your iCloud account, and copy the API key. The nylas auth config command stores the key locally so subsequent commands authenticate automatically.

# Configure your API key
nylas auth config
# Paste your API key when prompted

# Verify the connection
nylas auth whoami
# => Authenticated as you@icloud.com (iCloud)

3. Shared and subscribed iCloud calendars

iCloud calendars are often personal, household, or subscription-driven rather than enterprise-owned. A typical iCloud user has 3-5 calendars mixing owned, shared, and subscribed ICS feeds. The first check before writing automation is whether each calendar is owned (read-write), shared with edit access, or a read-only subscription like a holiday feed.

The nylas calendar list --json command returns every calendar on the connected iCloud account, including shared calendars from other Apple ID users and subscribed ICS feeds. The read_only field tells you which calendars accept writes.

# See every calendar and whether it is read-only
nylas calendar list --json | \
  jq -r '.[] | "\(.name) | read_only=\(.read_only) | id=\(.id)"'

# Pull events from one shared or subscribed calendar
nylas calendar events list --calendar cal_family_travel --days 14

4. Family calendars and travel workflows

iCloud Calendar's most common automation use cases are personal: family logistics, school pickups, travel itineraries, birthdays, and shared household planning. Apple reported over 2 billion active devices in its installed base as of January 2025, and many of those devices share family calendars through iCloud. The automation value here is personal coordination across Apple devices, not enterprise tenant administration.

The nylas calendar events create command supports all-day events for travel dates and birthdays. The --all-day flag creates events that span the entire day without a specific time, which is how Calendar.app displays vacations and holidays.

# Create a travel or family event
nylas calendar events create \
  --title "Family Vacation" \
  --start "2026-04-10" \
  --all-day

# Pull just the family or travel calendars you care about
nylas calendar list --json | \
  jq -r '.[] | select(.name | test("Family|Travel"; "i")) | {name, id}'

Events created through the CLI sync to Apple Calendar.app on iPhone, iPad, macOS, and iCloud.com. Sync typically completes within 15 seconds via Apple Push Notification service, so changes appear on all devices almost immediately.

5. Update, delete, and handle read-only feeds

Updating and deleting iCloud Calendar events works on any calendar where you have write access, but read-only subscribed calendars reject all mutations. iCloud users subscribe to ICS feeds more frequently than Google Workspace or Exchange users — holiday feeds, sports schedules, and school calendars are common. Apple's default refresh interval for subscribed ICS feeds ranges from 15 minutes to 1 week depending on the source.

The nylas calendar events update command modifies an existing event by its event ID. The nylas calendar events delete command removes it permanently. Before writing automation that creates or modifies events, filter the calendar list for writable calendars to avoid errors on subscribed feeds.

# Update an owned event
nylas calendar events update event_abc123 \
  --title "Dentist - Dr. Smith" \
  --start "2026-04-05 15:00" \
  --end "2026-04-05 16:00"

# Delete an event you own
nylas calendar events delete event_abc123

# Check read-only calendars before writing
nylas calendar list --json | \
  jq -r '.[] | select(.read_only == true) | .name'

6. Check availability across personal iCloud calendars

The Nylas CLI can check free/busy status across iCloud Calendar and other providers in a single query. The typical iCloud availability use case is a personal calendar layered with a work calendar from Google or Outlook, rather than a full enterprise tenant. The nylas calendar availability check command aggregates busy times across all connected calendars and returns open time slots.

The --duration flag on nylas calendar availability find accepts values in minutes. A 30-minute duration searches for 30-minute windows where all listed participants are free. The CLI checks up to 5 participants in a single query across any mix of providers.

# Check your free/busy status
nylas calendar availability check

# Find mutual availability with others
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 30

# Check availability for a specific date range
nylas calendar availability check \
  --start "2026-04-07" \
  --end "2026-04-11"

7. Core iCloud calendar commands

The Nylas CLI provides 6 core calendar subcommands: list, events list, events create, events update, events delete, and availability check. These commands work identically across iCloud, Gmail, Outlook, Exchange, Yahoo, and any CalDAV provider. The --days flag on events list controls how far ahead to look, defaulting to 7 days.

The --show-tz flag displays timezone information alongside each event, which is especially useful when iCloud Calendar events span multiple timezones for travel. The --participant flag can be repeated to add multiple attendees to a single event.

# List upcoming events
nylas calendar events list --days 14 --show-tz

# Create a standard event
nylas calendar events create \
  --title "Dentist Appointment" \
  --start "2026-04-05 14:00" \
  --end "2026-04-05 15:00"

# Create an event with participants
nylas calendar events create \
  --title "Team Lunch" \
  --start "2026-04-07 12:00" \
  --end "2026-04-07 13:00" \
  --participant alice@example.com \
  --participant bob@example.com

8. JSON output for scripting

The --json flag on any Nylas CLI calendar command returns structured JSON instead of the default human-readable table. JSON output enables piping calendar data into jq, Python, or any scripting language for automated reports, dashboards, or notifications. Each event object includes 12+ fields: title, start time, end time, participants, location, calendar ID, and more.

JSON mode is particularly useful for iCloud calendars where you need to separate owned calendars from read-only subscriptions, or build daily schedule summaries that combine personal and shared calendars into a single view. The examples here use jq to extract and reshape event data.

# List events as JSON
nylas calendar events list --json

# Extract just titles and times
nylas calendar events list --json | \
  jq -r '.[] | "\(.title) | \(.when.start_time) - \(.when.end_time)"'

# Count events per day this week
nylas calendar events list --days 7 --json | \
  jq '[.[] | .when.start_time | split("T")[0]] | group_by(.) | map({date: .[0], count: length})'

# Morning schedule summary
echo "=== Today's Schedule ==="
nylas calendar events list --days 1 --json | \
  jq -r '.[] | "  \(.when.start_time | split("T")[1] | split("+")[0] | .[0:5]) \(.title)"'

Apple Calendar.app vs Nylas CLI

Apple Calendar.app is a GUI-only application that cannot be scripted, piped to other commands, or run in CI/CD pipelines. Calendar.app supports AppleScript on macOS, but AppleScript cannot run on Linux, cannot produce JSON output, and requires a logged-in GUI session. The Nylas CLI runs in any terminal on macOS, Linux, or Windows, and its output can be piped directly into jq, grep, or Python for automation. The table compares 9 common calendar tasks across both tools.

iCloud-specific tips

iCloud Calendar has several behaviors that differ from Google Calendar and Outlook, particularly around shared calendars, read-only subscriptions, and cross-device sync. These tips cover the 6 most common issues developers encounter when automating iCloud Calendar from the command line, based on differences between Apple's CalDAV implementation and the REST APIs offered by other providers.

Shared calendars

iCloud lets you share calendars with other Apple ID users. Up to 100 people can share a single iCloud calendar, according to Apple's iCloud system limits. Shared calendars appear in nylas calendar list alongside your own. You can create and edit events on shared calendars if the owner granted you edit access. Read-only shared calendars show events but reject create/update operations.

# See all calendars including shared ones
nylas calendar list --json | \
  jq -r '.[] | "\(.name) (\(.id)) - read_only: \(.read_only)"'

Calendar subscriptions (ICS feeds)

iCloud supports subscribing to external ICS calendars (sports schedules, holidays, school calendars). These are read-only feeds that Apple polls at intervals ranging from every 15 minutes to once per week, depending on the source. Subscribed calendars appear in the calendar list but reject all create, update, and delete operations.

Siri Shortcuts alternative

On macOS and iOS, Siri Shortcuts can automate Calendar.app actions. But Shortcuts can't run on Linux, can't be invoked from SSH sessions, and can't produce JSON output. Shortcuts are also limited to the device they run on — they can't query calendars from a remote server. If you work primarily in a terminal or need server-side calendar automation, the Nylas CLI covers what Shortcuts can't.

CalDAV comparison

Next steps

• Manage calendar from the terminal — DST-aware scheduling, timezone locking, and AI-powered meeting finder
• iCloud Mail CLI: Read Emails from Terminal — read and search iCloud Mail from the CLI
• Send email from the terminal — compose and send from any provider
• How Apple's new CEO can automate iCloud email — AI triage, smart compose, and focus time protection for iCloud
• Give AI agents email access via MCP — let Claude or Cursor manage your calendar
• Full command reference — every calendar flag and subcommand
• RFC 4791 -- Calendaring Extensions to WebDAV (CalDAV) — the protocol behind iCloud calendar that the CLI abstracts over