SkillHub

apple-calendar-cli

v1.0.1

使用 apple-calendar-cli 在 macOS 14+ 上管理 Apple Calendar 事件，支持增删改查及 ISO 8601 日期格式。

Sourced from ClawHub, Authored by sichengchen

Installation

Please help me install the skill `apple-calendar-cli` from SkillHub official store. npx skills add sichengchen/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: - <id> — 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