Manage iCloud Calendar from the CLI

Apple's missing calendar API

Google has the Calendar API. Microsoft has Graph API. Apple has CalDAV and nothing else. There's no iCloud Calendar REST API, no Apple-provided CLI, and no SDK. According to Apple's developer documentation, iCloud Calendar is accessible only through CalDAV (RFC 4791).

CalDAV works, but the setup is painful. You need to:

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. For automation, that's a dead end.

1. Install

Run brew install nylas/nylas-cli/nylas (other methods). iCloud calendar access goes through Nylas's CalDAV connector, so you don't need to configure Apple's CalDAV endpoints manually.

2. Authenticate your iCloud account

Create an application at dashboard-v3.nylas.com and connect your iCloud account. Nylas handles Apple's authentication so you don't generate app-specific passwords or configure CalDAV endpoints yourself.

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

iCloud calendars are often personal, household, or subscription-driven rather than enterprise-owned. That changes the operational questions. The first thing to verify is not usually a tenant policy. It is whether the calendar is yours, shared with edit access, or just a read-only subscription.

# 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-id cal_family_travel --days 14

4. Family calendars and travel workflows

iCloud calendars are frequently about family logistics, school pickups, travel itineraries, birthdays, and shared household planning. That is what makes this page different from the Microsoft and Google ones. The automation value is usually clean personal coordination across Apple devices, not tenant administration.

# 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 your iPhone, iPad, macOS, and web clients. That cross-device consistency matters more here than room resources or tenant policy.

5. All-day events and read-only feeds

Another iCloud-specific nuance is how often listed calendars are not writable. Holiday feeds, sports schedules, and school calendars are commonly subscribed ICS feeds. Scripts that assume every listed calendar accepts writes will fail more often on iCloud than on Google Workspace or Exchange.

# 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. Availability across personal calendars

Availability checks still work across providers, but the common iCloud use case is a personal calendar mixed with another work calendar rather than a full Workspace tenant.

# 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

Once you know which calendars are writable, the day-to-day commands stay simple:

# 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

Use --json when you need to separate owned calendars from subscriptions or build travel and household summaries:

# 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

Calendar.app works well for visual scheduling, but it isn't scriptable. You can't pipe its output, trigger it from a cron job, or run it in CI.

iCloud-specific tips

Shared calendars

iCloud lets you share calendars with other Apple ID users. 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 every 15 minutes to 1 week depending on the source. Subscribed calendars appear in the list but won't accept event creation.

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. If you work primarily in a terminal or need server-side calendar automation, the CLI covers what Shortcuts can't.

Family calendars and travel workflows

iCloud calendars are often personal and household-oriented in a way the enterprise providers are not. Family calendars, school pickups, travel itineraries, sports subscriptions, and shared household planning are common patterns here. That makes the iCloud guide different from the Outlook and Exchange ones: the priority is usually clean personal automation across Apple devices, not tenant policy or room resources.

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

All-day events and Apple clients

Apple users also notice all-day and timezone behavior more quickly because the same event is expected to look identical on iPhone, iPad, macOS, and web. When you automate iCloud calendars, it is worth testing travel dates, birthdays, and other all-day events instead of only standard meetings. Those are the places where personal-calendar automation feels broken fastest.

Read-only subscriptions are common

Another iCloud-specific nuance is how often calendars are subscribed rather than owned. Holiday feeds, sports schedules, and school calendars are frequently read-only subscriptions. Scripts that assume every listed calendar accepts writes will fail more often on iCloud than on Google Workspace or Exchange.

CalDAV comparison

Next steps

• Manage calendar from the terminal — DST-aware scheduling, timezone locking, and AI-powered meeting finder
• List iCloud Mail from the terminal — read and search iCloud Mail from the CLI
• Send email from the terminal — compose and send from any provider
• Give AI agents email access via MCP — let Claude or Cursor manage your calendar
• Full command reference — every calendar flag and subcommand