Apple Reminders CLI
Manage Apple Reminders from the command line on macOS. List, add, edit, complete and delete reminders, filter by due date, with JSON output for agent use.
arcli: Apple Reminders CLI
arcli manages Apple Reminders on macOS via EventKit. Every command supports --json. Exit codes: 0 success, 1 runtime error, 2 validation error, 10 not authorized.
First run: arcli setup to grant Reminders access (System Settings > Privacy & Security > Reminders).
Lists
arcli lists [--json]
Returns { lists: [{ id, name, source, writable, open }] }. open is the number of incomplete reminders. Prefer --list-id <id> over a list name: ids are stable, names can repeat across accounts.
List Reminders
arcli reminders [<listName>] [--list-id <id>] [--due today|overdue|upcoming] \
[--all | --completed] [--flagged] [--limit <n>] [--json]
- No list means every list
- Open reminders only by default;
--allincludes completed,--completedreturns only completed --due todayincludes overdue, like the Today view in Reminders.app;overdueandupcomingare exclusive- Sorted by due date, undated last
--flaggedadds a Reminders.app call (about a second) and setsflagged: trueon each result
Show One
arcli show <id> [--json]
Returns { reminder } including flagged.
Add
arcli add <title> [--list <name> | --list-id <id>] [--due <when>] \
[--notes <text>] [--url <url>] [--priority none|low|medium|high] [--flagged] [--json]
No list means the default list for new reminders. A timed due date also gets an alert at that time.
Edit
arcli edit <id> [--title <text>] [--list <name> | --list-id <id>] [--due <when> | --no-due] \
[--notes <text>] [--url <url>] [--priority none|low|medium|high] [--flagged | --unflagged] [--json]
--list moves the reminder. --notes "" clears notes. --no-due clears the due date and its alerts.
Complete
arcli complete <id> [--json]
arcli uncomplete <id> [--json]
Delete
arcli delete <id> -y [--json]
Without -y it asks for confirmation, and refuses when there is no terminal. Agents must pass -y. There is no undo, so arcli show <id> first to confirm the target.
Due Formats
YYYY-MM-DD(all day)YYYY-MM-DD HH:mmorYYYY-MM-DDTHH:mmtoday,tomorrow, or either with a time:"tomorrow 09:00"
Output due is local time: YYYY-MM-DD or YYYY-MM-DDTHH:mm, or null.
Reminder Shape
{ id, title, list, listId, due, completed, completedAt, priority, notes, url, createdAt, modifiedAt }, plus flagged on show, add, edit and reminders --flagged. priority is none, low, medium or high.
Agent Best Practices
- Always use
--jsonand checkokbefore proceeding - Use
arcli reminders --jsonto find ids beforeedit,completeordelete - Use
--list-idfromarcli listsinstead of names - Flags need Automation access to Reminders.app; a
NOT_AUTHORIZEDerror on a flag call names the setting - macOS only
Error Codes
| Code | Meaning |
|---|---|
NOT_AUTHORIZED | Reminders access, or Automation access for flags, not granted |
LIST_NOT_FOUND | No list with that name or id |
AMBIGUOUS_LIST | More than one list with that name; use --list-id |
REMINDER_NOT_FOUND | No reminder with that id |
MISSING_REQUIRED | A required argument is missing |
INVALID_ARGUMENT | A flag value is invalid |
SAVE_FAILED / DELETE_FAILED | Reminders refused the change |
FLAG_FAILED | The reminder was saved but Reminders.app could not set the flag |
- Downloads
- 178All time
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v0.1.2
- License
- MIT-0
