accli-plus: Apple Calendar CLI

manage apple calendar on macos via EventKit. all commands support --json for structured output. exit codes: 0=success, 1=runtime error, 2=validation error, 10=auth error.

intent

accli-plus lets you programmatically manage apple calendar from the command line on macOS. create, modify, delete, search, and export events. check free/busy slots. all operations return JSON for agent parsing. use this when you need calendar automation without GUI interaction, or when building workflows that read and write calendar data to apple's EventKit backend.

inputs

system requirements

• macOS only (darwin kernel)
• accli binary installed: npm install -g @gopaljigaur/accli

setup (one-time)

• run accli setup to grant full calendar access in System Settings > Privacy & Security > Calendars
• requires "Full Access" permission, not "Add Only" (will fail with NOT_AUTHORIZED error code 10 otherwise)
• on first use, the system will prompt for permission; click "OK" in the dialog

configuration

• optional: set a default calendar via accli config set-default --calendar-id <id> to avoid passing --calendar-id on every command
• config stored in ~/.acclirc (override with env var ACCLI_CONFIG_PATH)
• if no default is set, calendar name or ID must be passed explicitly to each command

external state

• calendar IDs are stable UUIDs from EventKit; calendar names can change and should not be relied on for targeting
• alerts (reminders) are stored in minutes before event start time
• recurrence rules support daily, weekly, monthly, yearly; mutually exclusive: either --recur-count OR --recur-end, not both

procedure

step 1: list calendars

accli calendars [--json]

input: none (reads from EventKit) output: JSON array with fields id (stable UUID), name (user-facing, changeable), source (icloud, local, etc), index (position), writable (boolean) use this to discover calendar IDs before running other commands

step 2: list events in a date range

accli events [<calendarName>] [--calendar-id <id>] --from <date> --to <date> [--json]

input: calendar (positional name, --calendar-id flag, or config default), --from <YYYY-MM-DD>, --to <YYYY-MM-DD> output: JSON array of events with id, summary, start, end, location, description, alerts, recurring note: calendar param is required; omit only if default is configured

step 3: fetch single event detail

accli event [<calendarName>] <eventId> [--calendar-id <id>] [--json]

input: calendar (name, ID, or default), event UUID output: full event object including alerts array (minutes before start), recurrence rules, attendees if applicable use before update/delete to confirm you have the right event

step 4a: create event (timed)

accli create <calendarName> --summary <text> --start <YYYY-MM-DDTHH:mm> --end <YYYY-MM-DDTHH:mm> \
  [--location <text>] [--description <text>] \
  [--alert <minutes>] [--alert <minutes>] \
  [--recur daily|weekly|monthly|yearly] [--recur-count <n>] [--recur-end <YYYY-MM-DD>] \
  [--json]

input: calendar name, --summary, --start and --end in ISO format with time (HH:mm or HH:mm:ss), optional location, description, alerts (repeatable), recurrence config output: JSON object with new id, summary, start, end, location, description, alerts, recurring, calendarId validation: start must not be after end (error code INVALID_RANGE)

step 4b: create event (all-day)

accli create <calendarName> --summary <text> --start <YYYY-MM-DD> --end <YYYY-MM-DD> --all-day \
  [--location <text>] [--description <text>] \
  [--alert <minutes>] [--recur daily|weekly|monthly|yearly] [--recur-count <n>] [--recur-end <YYYY-MM-DD>]

input: same as 4a, but use date-only format, include --all-day flag output: event object with allDay: true note: alerts on all-day events are still in minutes before start (interpreted as start of day)

step 5: update event

accli update <calendarName> <eventId> \
  [--summary <text>] [--start <datetime>] [--end <datetime>] \
  [--location <text>] [--description <text>] \
  [--alert <minutes>] [--alert <minutes>] \
  [--dry-run] [--json]

input: calendar name/ID, event ID, any subset of optional fields output: JSON with ok: true and updated event object; or if --dry-run, { dryRun: true, wouldUpdate: { eventId, changes } } (no write) note: --alert flag on update replaces all existing alerts; omit to keep alerts unchanged

step 6: delete event

accli delete <calendarName> <eventId> [--dry-run] [--json]

input: calendar name/ID, event ID output: JSON with ok: true and { dryRun: true, wouldDelete: { id, summary, calendar, start, end } } if dry-run; empty success response if confirmed behavior: --dry-run shows what would be deleted without modifying calendar

step 7: search events

accli search --query <text> [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--calendar-id <id>] [--json]

input: --query (case-insensitive text), optional date range, optional calendar ID output: JSON array of matching events (searches summary, location, description fields), each with id, summary, calendarId, start, end behavior: if no --calendar-id, searches all calendars; always returns calendarId for targeting

step 8: export events

accli export --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--calendar-id <id>] [--json]

input: --from, --to (date range), optional calendar ID output: JSON { calendars: [{ id, name, source, events: [...], truncated: boolean }], totalEvents: number, truncated: boolean } behavior: each calendar truncates at 500 events and sets truncated: true if exceeded; check this field to know if full export was captured

step 9: check free/busy

accli freebusy --from <YYYY-MM-DDTHH:mm> --to <YYYY-MM-DDTHH:mm> [--calendar-name <name>] [--json]

input: --from and --to (datetime range with time), optional calendar name output: JSON array of busy time slots (start, end, summary) across specified calendars behavior: returns only occupied slots; absence of slots in output means full availability

step 10: configure defaults

accli config set-default --calendar-id <id> [--json]
accli config show [--json]
accli config clear [--json]

input: --calendar-id for set-default, no args for show/clear output: JSON confirmation or config dump behavior: persists to ~/.acclirc (or $ACCLI_CONFIG_PATH)

decision points

if calendar access not granted (error code 10: NOT_AUTHORIZED)

• on first run, accli setup will prompt system dialog; user must click "OK" in System Settings > Privacy & Security > Calendars and set to "Full Access" (not "Add Only")
• if denied, all commands will fail with code 10; no fallback; setup must be completed before proceeding

if calendar name is ambiguous (multiple calendars with same name)

• error code AMBIGUOUS_CALENDAR
• use accli calendars --json to list all calendars and find stable IDs
• always prefer --calendar-id <uuid> over calendar name in production workflows

if calendar ID not found (error code CALENDAR_NOT_FOUND)

• verify ID exists: run accli calendars --json and check the id field
• if calendar was deleted in macOS Calendar app, it is gone from EventKit and cannot be accessed

if event ID not found (error code EVENT_NOT_FOUND)

• use accli search --query <summary> to locate the event first
• event IDs are stable within EventKit but deleted events cannot be restored via this tool

if --alert flag is omitted on update

• all existing alerts are preserved unchanged
• if you want to remove all alerts, pass no --alert flags and existing alerts persist; there is no explicit "clear alerts" operation (workaround: update with a dummy alert, then update again to remove it, or manually edit in Calendar.app)

if --recur-count and --recur-end are both provided

• error code INVALID_ARGUMENT
• choose one: --recur-count 5 (5 occurrences) OR --recur-end 2025-12-31 (repeat until date), not both

if start datetime is after end datetime

• error code INVALID_RANGE
• validation happens before any write; command exits with code 2

if --from or --to are missing on events/export

• error code MISSING_REQUIRED
• date range is required; no default range is assumed

if running on non-macOS (linux, windows)

• accli binary will not run or will fail at runtime
• check uname -s returns "Darwin" before attempting
• this skill is macOS-only; no cross-platform version exists

if export hits the 500-event-per-calendar limit

• response includes truncated: true for that calendar
• use narrower date ranges or export individual calendars with --calendar-id to get full dataset

if network timeout or EventKit service is unresponsive

• exit code 1 (runtime error)
• no automatic retry; caller should implement backoff and retry logic

output contract

all commands with --json flag return valid JSON to stdout. error responses include ok: false and error: { code, message }. success responses vary by command but follow this structure:

calendars:

[
  { "id": "<uuid>", "name": "Personal", "source": "icloud", "index": 0, "writable": true }
]

events/event/search:

{
  "id": "<uuid>",
  "summary": "Team standup",
  "start": "2025-01-15T09:00:00",
  "end": "2025-01-15T09:30:00",
  "location": "Conference Room A",
  "description": "Daily sync",
  "calendarId": "<uuid>",
  "alerts": [5, 15],
  "recurring": false,
  "allDay": false
}

create/update:

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

update --dry-run:

{
  "dryRun": true,
  "wouldUpdate": {
    "eventId": "<uuid>",
    "changes": {
      "summary": "New title",
      "start": "2025-01-15T10:00:00"
    }
  }
}

delete:

{
  "ok": true
}

delete --dry-run:

{
  "dryRun": true,
  "wouldDelete": {
    "id": "<uuid>",
    "summary": "Team standup",
    "calendar": "Personal",
    "start": "2025-01-15T09:00:00",
    "end": "2025-01-15T09:30:00"
  }
}

export:

{
  "calendars": [
    {
      "id": "<uuid>",
      "name": "Personal",
      "source": "icloud",
      "events": [ ... ],
      "truncated": false
    }
  ],
  "totalEvents": 42,
  "truncated": false
}

freebusy:

[
  {
    "start": "2025-01-15T10:00:00",
    "end": "2025-01-15T10:30:00",
    "summary": "Team standup"
  }
]

config:

{
  "ok": true,
  "defaultCalendarId": "<uuid>"
}

error response (any command):

{
  "ok": false,
  "error": {
    "code": "NOT_AUTHORIZED",
    "message": "Calendar access not granted. Run `accli setup` and enable Full Access."
  }
}

file output: none (all output is stdout JSON or stderr error text). config stored in ~/.acclirc as text file.

outcome signal

the skill worked if:

• command exits with code 0 and stdout is valid JSON matching the output contract above
• ok: true field is present in response (for commands that return it)
• for destructive ops (delete, update), use --dry-run first to verify target event matches expectation
• event ID returned from create can be used immediately in subsequent update/delete/event commands
• search returns non-empty array when matching events exist, empty array when none match
• export includes all events within date range without data loss (check truncated field is false)
• freebusy returns empty array when fully available, non-empty array with start/end/summary for occupied slots
• calendar ID from calendars command matches the ID in event responses under calendarId field