{"skill":{"slug":"accli-plus","displayName":"Apple Calendar CLI Plus","summary":"Manage Apple Calendar events from the command line on macOS — create, update, delete, search, export, and check availability with full JSON output for agent...","description":"---\nname: accli\ndescription: Manage Apple Calendar events from the command line on macOS — create, update, delete, search, export, and check availability with full JSON output for agent use.\nauthor: gopaljigaur\nlicense: MIT\nplatform: macOS\nrequires:\n  binaries: [accli]\n  install: \"npm install -g @gopaljigaur/accli\"\ntags: [calendar, macos, productivity, apple, events]\n---\n\n# accli — Apple Calendar CLI\n\n`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.\n\n**First run:** `accli setup` to grant Calendar permissions (Full Access required in System Settings > Privacy & Security > Calendars).\n\n## Calendars\n\n```bash\naccli calendars [--json]\n```\n\nReturns list of calendars with `id`, `name`, `source`, `index`, `writable`. Always prefer `--calendar-id <id>` over calendar name — IDs are stable, names are not.\n\n## Events\n\n```bash\naccli events [<calendarName>] [--calendar-id <id>] --from <date> --to <date> [--json]\n```\n\nLists events in a date range. Calendar is required (use name, `--calendar-id`, or set a default via `accli config set-default`).\n\n## Single Event\n\n```bash\naccli event [<calendarName>] <eventId> [--calendar-id <id>] [--json]\n```\n\nFetches full event detail including alerts array (minutes before start).\n\n## Create Event\n\n```bash\naccli create <calendarName> --summary <text> --start <datetime> --end <datetime> \\\n  [--location <text>] [--description <text>] [--all-day] \\\n  [--alert <minutes>] [--alert <minutes>] \\\n  [--recur daily|weekly|monthly|yearly] [--recur-count <n>] [--recur-end <YYYY-MM-DD>] \\\n  [--json]\n```\n\n- `--alert` is repeatable — adds one alert per flag (minutes before start)\n- `--recur-end` and `--recur-count` are mutually exclusive\n- All-day events: use `YYYY-MM-DD` for `--start` and `--end`\n- Timed events: use `YYYY-MM-DDTHH:mm`\n\n## Update Event\n\n```bash\naccli update <calendarName> <eventId> \\\n  [--summary <text>] [--start <datetime>] [--end <datetime>] \\\n  [--location <text>] [--description <text>] \\\n  [--alert <minutes>] [--alert <minutes>] \\\n  [--dry-run] [--json]\n```\n\n`--alert` on update replaces all existing alerts. Omit `--alert` to leave alerts unchanged.\n`--dry-run` returns `{ dryRun: true, wouldUpdate: { eventId, changes } }` without modifying anything.\n\n## Delete Event\n\n```bash\naccli delete <calendarName> <eventId> [--dry-run] [--json]\n```\n\n`--dry-run` returns `{ dryRun: true, wouldDelete: { id, summary, calendar, start, end } }` without deleting.\n\n## Search\n\n```bash\naccli search --query <text> [--from <date>] [--to <date>] [--calendar-id <id>] [--json]\n```\n\nCase-insensitive search across summary, location, and description. Searches all calendars unless `--calendar-id` is provided. Returns events with `calendarId` field for targeting.\n\n## Export\n\n```bash\naccli export --from <date> --to <date> [--calendar-id <id>] [--json]\n```\n\nExports all events grouped by calendar. Response: `{ calendars: [{ id, name, source, events, truncated }], totalEvents, truncated }`. Each calendar truncates at 500 events per calendar and sets `truncated: true` if hit.\n\n## Free/Busy\n\n```bash\naccli freebusy --from <datetime> --to <datetime> [--calendar-name <name>] [--json]\n```\n\nReturns busy time slots across calendars.\n\n## Config\n\n```bash\naccli config set-default --calendar-id <id> [--json]\naccli config show [--json]\naccli config clear [--json]\n```\n\nPersists default calendar to `~/.acclirc` (override with `ACCLI_CONFIG_PATH`). Commands that require a calendar use the default when no calendar is specified.\n\n## DateTime Formats\n\n- Timed: `YYYY-MM-DDTHH:mm` or `YYYY-MM-DDTHH:mm:ss`\n- Date-only (all-day events, --from/--to): `YYYY-MM-DD`\n\n## Agent Best Practices\n\n- Always use `--json` for programmatic parsing\n- Use `--calendar-id` not calendar name (stable across renames)\n- Use `--dry-run` before destructive operations to confirm target event\n- Use `accli search` to find event IDs before update/delete\n- Check `ok: false` in JSON response before proceeding\n- `accli export` is suitable for full calendar backup; check `truncated` field\n- Multiple alerts: repeat `--alert` flag — e.g. `--alert 5 --alert 15`\n- macOS only — do not attempt on non-darwin systems\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| `NOT_AUTHORIZED` | Calendar access not granted or set to Add Only |\n| `CALENDAR_NOT_FOUND` | Calendar ID or name not found |\n| `AMBIGUOUS_CALENDAR` | Multiple calendars with same name — use `--calendar-id` |\n| `EVENT_NOT_FOUND` | Event ID not found in calendar |\n| `MISSING_REQUIRED` | Required flag missing |\n| `INVALID_ARGUMENT` | Invalid flag value |\n| `INVALID_RANGE` | Start is after end |\n","topics":["Calendar","Apple","Events","Macos","Json"],"tags":{"latest":"1.2.4"},"stats":{"comments":0,"downloads":551,"installsAllTime":20,"installsCurrent":0,"stars":0,"versions":4},"createdAt":1777806922110,"updatedAt":1778492833926},"latestVersion":{"version":"1.2.4","createdAt":1778009400738,"changelog":"Release 1.2.4","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"gopaljigaur","userId":"s177y2ebzrk8tv43ycxd02r8tn8617j3","displayName":"Gopalji Gaur","image":"https://avatars.githubusercontent.com/u/30744909?v=4"},"moderation":null}