Apple Calendar CLI

Apple Calendar CLI — Agent Skill

You have access to apple-calendar-cli, a command-line tool for managing Apple Calendar events via EventKit on macOS.

Prerequisites

macOS 14+ required

Install: brew install sichengchen/tap/apple-calendar-cli

Calendar access permission must be granted (System Settings > Privacy & Security > Calendars)

Date Format

All dates use ISO 8601 format:

Date only: YYYY-MM-DD (interpreted as start of day in local timezone)

Date and time: YYYY-MM-DDTHH:MM:SS (local timezone)

Full ISO 8601: YYYY-MM-DDTHH:MM:SSZ or with offset

Global Options

--json — Output results as structured JSON (available on all commands)

--version — Show version

--help / -h — Show help

Always use --json when calling from an agent for reliable parsing.

Commands

list-calendars

List all available calendars.

apple-calendar-cli list-calendars --json

JSON output — array of objects:

[
  {
    "identifier": "CALENDAR-ID",
    "title": "Work",
    "type": "calDAV",
    "source": "iCloud",
    "color": "#1BADF8",
    "isImmutable": false
  }
]

Use identifier to filter events or target a specific calendar when creating events.

list-events

List events within a date range.

apple-calendar-cli list-events --json
apple-calendar-cli list-events --from 2026-02-22 --to 2026-02-28 --json
apple-calendar-cli list-events --from 2026-02-22 --to 2026-02-28 --calendar CALENDAR-ID --json

Options:

--from — Start date (default: today)

--to — End date (default: 7 days from start)

--calendar — Filter by calendar identifier

JSON output — array of event objects:

[
  {
    "identifier": "EVENT-ID",
    "title": "Team standup",
    "startDate": "2026-02-22T10:00:00-08:00",
    "endDate": "2026-02-22T10:30:00-08:00",
    "isAllDay": false,
    "location": "Conference Room A",
    "notes": null,
    "calendarTitle": "Work",
    "calendarIdentifier": "CALENDAR-ID",
    "url": null,
    "hasRecurrenceRules": true
  }
]

get-event

Get full details of a single event.

apple-calendar-cli get-event EVENT-ID --json

JSON output — single event object (same schema as list-events items).

create-event

Create a new calendar event.

apple-calendar-cli create-event \
  --title "Meeting with Alice" \
  --start "2026-02-23T14:00:00" \
  --end "2026-02-23T15:00:00" \
  --json
apple-calendar-cli create-event \
  --title "All-day conference" \
  --start "2026-03-01" \
  --end "2026-03-02" \
  --all-day \
  --calendar CALENDAR-ID \
  --location "Convention Center" \
  --notes "Bring laptop" \
  --url "https://example.com/conf" \
  --json

Required options:

--title — Event title

--start — Start date/time

--end — End date/time (must be after start)

Optional options:

--calendar — Calendar identifier (default: system default calendar)

--notes — Event notes

--location — Event location

--all-day — Mark as all-day event

--url — Event URL

--recurrence — Recurrence rule: daily, weekly, monthly, yearly

--recurrence-end — End date for recurrence

--recurrence-count — Number of occurrences

--attendees — Comma-separated email addresses

--alert — Alert offset (e.g., 15m, 1h, 1d)

JSON output — the created event object with its new identifier.

update-event

Update an existing event (partial update — only specified fields change).

apple-calendar-cli update-event EVENT-ID --title "New title" --json
apple-calendar-cli update-event EVENT-ID \
  --start "2026-02-23T15:00:00" \
  --end "2026-02-23T16:00:00" \
  --location "Room B" \
  --json

Required argument:

— Event identifier

Optional options:

--title — New title

--start — New start date/time

--end — New end date/time

--calendar — Move to different calendar (by identifier)

--notes — New notes

--location — New location

--url — New URL

JSON output — the updated event object.

delete-event

Delete a calendar event.

apple-calendar-cli delete-event EVENT-ID --json

JSON output:

{
  "deleted": true,
  "event": { ... }
}

Common Agent Workflows

Find and reschedule an event

# 1. List events to find the one to reschedule
apple-calendar-cli list-events --from 2026-02-22 --to 2026-02-28 --json
2. Get full details
apple-calendar-cli get-event EVENT-ID --json
3. Update the time
apple-calendar-cli update-event EVENT-ID \
  --start "2026-02-24T14:00:00" \
  --end "2026-02-24T15:00:00" \
  --json

Create an event on a specific calendar

# 1. List calendars to find the right one
apple-calendar-cli list-calendars --json
2. Create the event on that calendar
apple-calendar-cli create-event \
  --title "Dentist" \
  --start "2026-02-25T09:00:00" \
  --end "2026-02-25T10:00:00" \
  --calendar CALENDAR-ID \
  --json

Check today's schedule

Date-only values resolve to midnight (00:00:00), so --to must be the next day to cover the full day:

# Correct: covers 2026-02-22 00:00 to 2026-02-23 00:00
apple-calendar-cli list-events --from 2026-02-22 --to 2026-02-23 --json

Error Handling

Calendar access denied: User needs to grant access in System Settings > Privacy & Security > Calendars

Event not found: The event ID may be stale — list events again to get current IDs

Invalid date format: Use ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)

End before start: Ensure the end date/time is after the start date/time

macOS 14+ required

Install: brew install sichengchen/tap/apple-calendar-cli

Calendar access permission must be granted (System Settings > Privacy & Security > Calendars)