Manage iCloud Calendar from the Command Line

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 the Nylas CLI

# macOS (Homebrew)
brew install nylas/nylas-cli/nylas

# macOS, Linux, or WSL
curl -fsSL https://cli.nylas.com/install.sh | bash

# Verify
nylas --version

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. List calendar events

# List upcoming events (next 7 days)
nylas calendar events list

# Next 14 days
nylas calendar events list --days 14

# Show timezone info
nylas calendar events list --show-tz

# Convert all times to a specific timezone
nylas calendar events list --timezone America/Los_Angeles

All your iCloud calendars appear: Home, Work, and any shared or subscribed calendars. Use nylas calendar list to see calendar IDs, then filter by calendar:

# List all calendars
nylas calendar list

# Events from a specific calendar only
nylas calendar events list --calendar-id cal_abc123

4. Create events

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

# All-day event
nylas calendar events create \
  --title "Family Vacation" \
  --start "2026-04-10" \
  --all-day

# 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

# With location
nylas calendar events create \
  --title "Coffee Meeting" \
  --start "2026-04-08 09:00" \
  --end "2026-04-08 09:30" \
  --location "Blue Bottle Coffee, Ferry Building"

Events created through the CLI sync to Apple Calendar.app on all your devices within seconds. iCloud push notifications work the same as events created natively.

5. Update and delete events

# Update an event's time
nylas calendar events update event_abc123 \
  --start "2026-04-05 15:00" \
  --end "2026-04-05 16:00"

# Change the title
nylas calendar events update event_abc123 \
  --title "Dentist - Dr. Smith"

# Delete an event
nylas calendar events delete event_abc123

# Delete with confirmation prompt
nylas calendar events delete event_abc123 --confirm

6. Check availability and find meeting times

Availability checks work across providers. If you have an iCloud personal calendar and a Google Workspace calendar, Nylas checks both:

# Check your free/busy status
nylas calendar availability check

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

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

7. JSON output for scripting

Every command supports --json for machine-readable output. Pipe into jq for filtering and transformation:

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

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