Apple Reminders

Apple Reminders

Overview

apple-reminders is a built-in native command backed by EventKit. It exposes five verbs — list, create, update, complete, delete — over reminder titles, due dates, lists, priorities, notes, and completion state. Every call prints one JSON envelope to stdout.

The command is small, but three of its behaviours fail silently and successfully: a mistyped list name, an unparseable due date, and a truncated read all return ok: true. Most of this skill exists to keep those three from turning into wrong answers or misplaced tasks. Read references/cli.md for the full contract — flags, JSON shapes, error codes, and the exact date grammar.

Copy code
apple-reminders list     [--incomplete|--completed] [--list <name>] [--limit <N>]
apple-reminders create   --title <t> [--due <dt>] [--list <name>] [--priority <0-9>] [--notes <text>]
apple-reminders update   --id <id> [--title <t>] [--due <dt>] [--list <name>] [--priority <0-9>] [--notes <text>]
apple-reminders complete --id <id> [--undo]
apple-reminders delete   --id <id>

Add --compact to minimize JSON, -q to print only the data field. Prefer --compact for large reads to save context.

Run apple-reminders --help when you are unsure whether an option still exists — the help text is authoritative for the build you are running, and this reference may lag it.

The command is iOS-only. If it is not on PATH, say that reminder access is not available on this device. Do not reach for a workaround: there is no supported path to Reminders data outside this command, so do not try to install an adapter, script around it, or read Reminders storage directly.

Three checks before any write

These are not style preferences. Each one prevents a wrong result that the command itself reports as success.

1. Resolve the exact list title from a read. Never pass a guessed name.

--list matches by case-insensitive substring, so --list Work also matches Workout, and when several titles match, EventKit's calendar order decides which one wins — not you. Worse, on create an unmatched --list is not an error: the reminder is silently saved to the default list and the response still says ok: true. So read first, pick the exact title, then write, then confirm the list field in the response is the list you intended.

Empty lists never appear in list output, because list titles are only observable through the reminders inside them. If the user names a list you cannot find, say it is either empty or nonexistent — do not create the task somewhere else and hope.

2. Compute due dates as absolute local datetimes yourself.

Accepted forms are YYYY-MM-DD, YYYY-MM-DDTHH:MM, YYYY-MM-DDTHH:MM:SS (interpreted in the device's local timezone), and full ISO 8601 with an offset or Z. Relative offsets are accepted only into the past (-7d, -2h, -30m); there is no +3d form.

Anything else — tomorrow, next Monday, +1d, 3d, 내일 — fails to parse, and a failed parse is dropped without an error: the reminder is created or updated with no due-date change and the command still exits 0. So resolve the user's wording into a concrete date and time before you build the command, and state the date you chose in your answer so a misreading is visible.

Two consequences worth knowing: YYYY-MM-DD alone becomes 00:00 local, since this command has no all-day form; and create does not echo due back, so after any create --due you must read the reminder back to confirm the date actually landed. update does echo due, so its own response is the confirmation.

3. Treat a truncated read as "I have not seen the data yet".

--limit defaults to 100, and result order is not guaranteed — so a truncated read is an arbitrary subset, not the first 100 by date. When data contains _warning and total_available, you cannot say anything about the whole set: "nothing is overdue" may simply mean the overdue items were outside the window.

Re-run with a narrower scope (--incomplete, --list <exact title>) or with --limit above total_available, then answer. Say so if you deliberately answer from a bounded scope.

Workflow

1. Read the real state first. Ground every answer in actual titles, list names, due dates, and completion state. For briefings use one --incomplete read; --incomplete includes reminders with no due date, which is what you want for an inbox view.
2. Normalize time language into explicit dates, times, and weekdays before reasoning or writing. Use the device's local timezone.
3. Keep reads bounded by list, completion state, and limit — the three filters that exist. There is no date-range or text-search filter, so date grouping and keyword matching happen on your side, after the read.
4. Target writes by id only. Get id from a list read. Never write against a title you have not resolved to a single id. If several reminders share a title, disambiguate by list, due date, or notes, and name which one you chose.
5. Verify after writing. update and complete return post-write state — read it, don't assume. create returns only id, title, and list, so verify due date, priority, and notes with a follow-up read when they matter. Never treat a zero exit status or a bare ok: true as proof the change landed the way you intended: all three silent failures above exit 0 and report success.
6. Report the exact affected set — titles, lists, and dates — not a count.
7. Do not retry a failed write blindly. Check error.code first: authorization_denied needs the user to grant Reminders access in Settings, and retrying will not help; invalid_args means fix the command; no_data means the id no longer resolves — re-read before concluding the reminder is gone.

Write safety

This skill supports standing delegation — a user who has told you to act on their reminders without checking in each time has granted it, and asking again on every write makes the skill useless for the exact people who want it. So when standing delegation applies, execute high-impact writes without stopping for a separate confirmation.

Delegation removes the prompt, not the evidence. Every delegated write must still be bounded to a target set you enumerated from a read, verified by read-back, and reported afterward with the exact items affected — that report is what makes the change reviewable after the fact, which is the whole basis for skipping the prompt. When standing delegation does not apply, restate the qualifying set and scope before writing.

Preserve everything the user did not ask to change. update is a patch: flags you omit are left untouched, so pass only the fields you intend to change. Never send a field "to be safe".

Match the care to how recoverable each verb is:

• complete is fully reversible with complete --id <id> --undo. Lowest risk. Prefer completing over deleting when the user's intent is "this is done", and when they say "clear" or "clean up", ask which they mean if it is not obvious from context — the two are not equivalent and only one is undoable.
• update overwrites the previous value with no undo. Capture the current value from your read before patching, and report old → new so the user can reverse it manually.
• delete is the only irreversible verb here. This skill cannot guarantee whether a deletion made through this command is recoverable from the Reminders app's Recently Deleted, so do not tell the user it is. Before deleting, capture title, list, due, priority, and notes, and include them in your report so the reminder can be recreated by hand if the deletion was wrong.
• Bulk changes need an enumerated target set before the first write, never a filter applied blindly. Keep batches small enough to report individually. If any single write returns ok: false, stop and report what has already been applied — do not continue through the rest of the batch, because a partially applied bulk change that is reported as complete is far harder to recover from than a stopped one.

Priority is inverted and unvalidated: 1 is the highest, 5 is medium, 9 is the lowest, 0 is none. Map the user's words to that scale (high → 1, medium → 5, low → 9) and never pass a number the user gave you as if it were a 1–10 ranking.

Ids from update, complete, and delete are resolved by scanning the whole reminder store with a 10-second cap. On a large store, a no_data "Reminder not found" can be that timeout rather than a missing reminder — re-read before telling the user their reminder is gone.

Output conventions

Name the list for every reminder when location matters, and use exact dates with weekdays (Fri 2026-08-07) rather than "in 3 days". A missing or null due date means unscheduled, not undated-and-fine.

A due time of exactly 00:00 is most likely an all-day reminder created in the Reminders app, not a midnight deadline — all-day items surface as T00:00:00 here and cannot be told apart from timed midnight ones. Present those as a date, and never "fix" one by writing a time onto it.

Do not surface a reminder's notes unless the user asked for them or they are needed to tell two otherwise identical candidates apart. Notes routinely hold private detail — medical, financial, personal — that the user did not ask to have read back, and a briefing is not a reason to print it. Keep raw JSON, ids, and local file paths out of the user-facing answer too; use them, don't display them.

For briefings, build the groups yourself from one --incomplete read, using the device's local timezone and skipping groups that are empty:

• Overdue — due before today's local midnight, oldest first
• Due today — due on today's local date, including times already past
• Upcoming — "this week" means after today through the coming Sunday; "the next seven days" means a rolling seven-day window. State which basis you used
• Unscheduled — no due date. Show at most 20, grouped by list, and report how many more were omitted, because an unscheduled inbox can be enormous
• Cleanup candidates — long-overdue or clearly stale items, only when asked

Keep it short and actionable. If your read was truncated or deliberately scoped, say so in one line rather than implying the briefing is complete.

What this command cannot do

Report these plainly when asked. Do not simulate them, do not write them into --notes as a silent substitute, and do not report success for something you did not do — the honest limitation is more useful than a fake feature.

When a request needs one of these, offer the closest honest alternative — a note in --notes, a priority instead of a flag, a separate list the user creates — and let the user decide. Do not invent a subcommand or flag to cover the gap. If the user wants the capability itself, point them at filing a feature request on the Minis repository rather than leaving them thinking it exists.

Examples

Daily briefing. "What's on my plate today?"

bashCopy code
apple-reminders list --incomplete --limit 200 --compact

Check _warning; if present, raise --limit above total_available and re-read. Then group into Overdue / Due today / Upcoming / Unscheduled, naming each list.

Capture into a named list. "Add pick up prescription to my errands list, Friday 6pm"

Read first to resolve the exact list title, compute the absolute datetime, create, then confirm the list field came back as the list you intended and read the due date back:

bashCopy code
apple-reminders list --incomplete --limit 200 --compact
apple-reminders create --title "Pick up prescription" --list "Errands" --due 2026-08-07T18:00
apple-reminders list --list "Errands" --incomplete --compact

Reschedule. "Push the tax filing task to next Monday."

Resolve the id from a read, patch only --due, and use the returned due as confirmation. Report Wed 2026-08-05 → Mon 2026-08-10.

Ambiguous list name. The user says "work list" and the read shows both Work and Workout. Do not pass --list work; it would match by substring and the winner is unpredictable. Pass the exact title you determined, or name both and ask which one when the reminder's content does not settle it.

Unsupported request. "Attach this screenshot to the visa reminder."

Say the on-device command has no attachment support, so you cannot do it from here; offer to reference the file path in the reminder's notes instead, and mention that attaching it by hand in the Reminders app is the only way to get a real attachment.