macOS Reminders

Use this skill when the task is about Apple Reminders.app on macOS.

Main Rule

Use only scripts/commands. Do not call scripts/applescripts directly.

Requirements

macOS with Reminders.app access
jq
remindctl for the preferred reminder backend

Account and list commands use AppleScript wrappers and still need jq to build JSON output. Reminder commands prefer remindctl and jq. They try remindctl from PATH, then /opt/homebrew/bin/remindctl, and use AppleScript fallback only when remindctl is not available.

Check remindctl access with:

remindctl status

Public Interface

Run commands from scripts/commands:

scripts/commands/account/*
scripts/commands/list/*
scripts/commands/reminder/*

Published reminder commands:

list.sh
count.sh
today.sh
overdue.sh
upcoming.sh
due-before.sh
due-range.sh
today-or-overdue.sh
create.sh
get.sh
get-by-id.sh
edit.sh
edit-by-id.sh
reschedule.sh
reschedule-by-id.sh
move.sh
move-by-id.sh
complete.sh
delete.sh
delete-by-id.sh
exists.sh
search.sh

scripts/commands/reminder/show.sh exists in the repo but is not part of the public interface.

Output Rules

Commands return JSON by default unless noted otherwise.
account/show.sh and list/show.sh open Reminders and return JSON like {"shown": true, ...}.
reminder/show.sh is not public and opens the UI without the normalized reminder JSON contract.
--json, --plain, and --format=plain|json are not supported.

Accounts

List accounts:

scripts/commands/account/list.sh

Read one account property:

scripts/commands/account/get.sh "iCloud" id
scripts/commands/account/get.sh "iCloud" reminders_count

Search accounts:

scripts/commands/account/search.sh exact-name "iCloud"
scripts/commands/account/search.sh text "cloud"

Get default account and default list:

scripts/commands/account/default-account.sh
scripts/commands/account/default-list.sh

Show an account in the app:

scripts/commands/account/show.sh "iCloud"

Lists

List all lists or lists in one account:

scripts/commands/list/list.sh
scripts/commands/list/list.sh "iCloud"

Create, edit, delete, and check existence:

scripts/commands/list/create.sh "Errands"
scripts/commands/list/create.sh "Errands" "#34C759" "list.bullet"
scripts/commands/list/edit.sh "Errands" name "Today"
scripts/commands/list/edit.sh "Today" color "#34C759"
scripts/commands/list/delete.sh "Today"
scripts/commands/list/exists.sh "Inbox"

Read one list property and search:

scripts/commands/list/get.sh "Inbox" id
scripts/commands/list/get.sh "Inbox" color
scripts/commands/list/search.sh exact-name "Inbox"
scripts/commands/list/search.sh text "Err" "iCloud"

Show a list in the app:

scripts/commands/list/show.sh "Inbox"

Reminders

Use the remindctl reminder ID or a unique ID prefix as the public reminder identity. Prefer --id for reminder read and write commands.

List and count:

scripts/commands/reminder/list.sh
scripts/commands/reminder/list.sh "Inbox"
scripts/commands/reminder/count.sh "Inbox"

Date filters:

scripts/commands/reminder/today.sh
scripts/commands/reminder/today.sh "Inbox"
scripts/commands/reminder/overdue.sh "Inbox"
scripts/commands/reminder/upcoming.sh 7 "Inbox"
scripts/commands/reminder/due-before.sh "2030-01-01" "Inbox"
scripts/commands/reminder/due-range.sh "2030-01-01" "2030-01-31" "Inbox"
scripts/commands/reminder/today-or-overdue.sh "Inbox"

Create:

scripts/commands/reminder/create.sh "Inbox" "Buy milk"
scripts/commands/reminder/create.sh "Inbox" "Buy milk" "2 liters" --priority high
scripts/commands/reminder/create.sh "Inbox" "Buy milk" --due "2026-03-14 10:00"

Read:

scripts/commands/reminder/get.sh --id "REMINDER-ID"
scripts/commands/reminder/get.sh --id "REMINDER-ID" body
scripts/commands/reminder/get-by-id.sh "REMINDER-ID" priority

Edit, move, complete, and delete:

scripts/commands/reminder/edit.sh --id "REMINDER-ID" body "3 liters"
scripts/commands/reminder/edit.sh --id "REMINDER-ID" due_date "missing"
scripts/commands/reminder/edit-by-id.sh "REMINDER-ID" priority medium
scripts/commands/reminder/reschedule.sh --id "REMINDER-ID" "2030-01-15"
scripts/commands/reminder/reschedule-by-id.sh "REMINDER-ID" "2030-01-15 12:00"
scripts/commands/reminder/move.sh --id "REMINDER-ID" "Errands"
scripts/commands/reminder/move-by-id.sh "REMINDER-ID" "Errands"
scripts/commands/reminder/complete.sh --id "REMINDER-ID"
scripts/commands/reminder/delete.sh --id "REMINDER-ID"
scripts/commands/reminder/delete-by-id.sh "REMINDER-ID"

Exists and search:

scripts/commands/reminder/exists.sh --id "REMINDER-ID"
scripts/commands/reminder/search.sh exact-name "Inbox" "Buy milk"
scripts/commands/reminder/search.sh id "REMINDER-ID"
scripts/commands/reminder/search.sh incomplete "Inbox"
scripts/commands/reminder/search.sh priority high "Inbox"
scripts/commands/reminder/search.sh has-due-date "Inbox"
scripts/commands/reminder/search.sh text "milk" "Inbox"

JSON Contract

Account object:

id
name
lists_count
reminders_count

List object:

id
name
container
color
emblem

Reminder object:

id
name
list
body
completed
priority
due_date

Reminder priority values:

none
low
medium
high

Scalar envelopes:

count: {"count": N, "list": "..."}
exists: {"exists": true, "id": "..."}
exists when not found: {"exists": false, "id": null}
property read: {"id": "...", "property": "...", "value": ...}
delete: {"deleted": true, "id": "..."}

Not Public

These reminder features are not part of the public interface:

show
flagged
container
creation_date
modification_date
completion_date
allday_due_date
remind_me_date
AppleScript reminder IDs

macos-reminders