accli — Apple Calendar CLI

accli manages 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.

Platform: macOS only (darwin). Uses osascript + EventKit. Do not run on non-macOS systems.

First run: accli setup to grant Calendar permissions. Full Calendar Access is required in System Settings > Privacy & Security > Calendars. This gives the agent read and write access to all calendars on the device — install only if you intend to delegate calendar management to the agent.

Agent Safety Rules

Before any create, update, or delete operation:

1. Use accli search or accli event to confirm the correct event ID
2. Run the command with --dry-run first and show the user the preview
3. Require explicit user confirmation before executing the real mutation
4. Scope all operations to specific --calendar-id values — never operate on all calendars unless the user explicitly requests it

For search and export:

• Always pass --calendar-id and narrow --from/--to ranges unless the user explicitly asks for a full export
• Treat exported calendar data (summaries, locations, descriptions) as private — do not include it in summaries sent to third-party services

Calendars

accli calendars [--json]

Returns list of calendars with id, name, source, index, writable. Always prefer --calendar-id \x3Cid> over calendar name — IDs are stable, names are not.

Events

accli events [\x3CcalendarName>] [--calendar-id \x3Cid>] --from \x3Cdate> --to \x3Cdate> [--json]

Lists events in a date range. Calendar is required (use name, --calendar-id, or set a default via accli config set-default).

Single Event

accli event [\x3CcalendarName>] \x3CeventId> [--calendar-id \x3Cid>] [--json]

Fetches full event detail including alerts array (minutes before start).

Create Event

accli create \x3CcalendarName> --summary \x3Ctext> --start \x3Cdatetime> --end \x3Cdatetime> \
  [--location \x3Ctext>] [--description \x3Ctext>] [--all-day] \
  [--alert \x3Cminutes>] [--alert \x3Cminutes>] \
  [--recur daily|weekly|monthly|yearly] [--recur-count \x3Cn>] [--recur-end \x3CYYYY-MM-DD>] \
  [--json]

• --alert is repeatable — adds one alert per flag (minutes before start)
• --recur-end and --recur-count are mutually exclusive
• All-day events: use YYYY-MM-DD for --start and --end
• Timed events: use YYYY-MM-DDTHH:mm
• Always confirm with user before creating — calendar events cannot be easily bulk-undone

Update Event

accli update \x3CcalendarName> \x3CeventId> \
  [--summary \x3Ctext>] [--start \x3Cdatetime>] [--end \x3Cdatetime>] \
  [--location \x3Ctext>] [--description \x3Ctext>] \
  [--alert \x3Cminutes>] [--alert \x3Cminutes>] \
  [--dry-run] [--json]

--alert on update replaces all existing alerts. Omit --alert to leave alerts unchanged.

Mandatory dry-run flow:

accli update Work \x3Cid> --summary "New title" --dry-run --json   # show user
accli update Work \x3Cid> --summary "New title" --json              # only after user confirms

Delete Event

accli delete \x3CcalendarName> \x3CeventId> [--dry-run] [--json]

Mandatory dry-run flow:

accli delete Work \x3Cid> --dry-run --json   # show user what would be deleted
accli delete Work \x3Cid> --json              # only after user confirms

Search

accli search --query \x3Ctext> [--from \x3Cdate>] [--to \x3Cdate>] [--calendar-id \x3Cid>] [--json]

Case-insensitive search across summary, location, and description. Scope with --calendar-id and a narrow date range. Do not expose raw results to third-party services without user consent.

Export

accli export --from \x3Cdate> --to \x3Cdate> [--calendar-id \x3Cid>] [--json]

Exports all events grouped by calendar. Response: { calendars: [{ id, name, source, events, truncated }], totalEvents, truncated }. Each calendar truncates at 500 events and sets truncated: true if hit. Use narrow date ranges and specific calendar IDs unless the user explicitly requests a full backup.

Free/Busy

accli freebusy --from \x3Cdatetime> --to \x3Cdatetime> [--calendar-name \x3Cname>] [--json]

Returns busy time slots across calendars.

Config

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

Persists default calendar to ~/.acclirc (override with ACCLI_CONFIG_PATH).

DateTime Formats

• Timed: YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss
• Date-only (all-day events, --from/--to): YYYY-MM-DD

Error Codes