Apple Reminders via remindctl: add, list, complete from the terminal

Apple Reminders is a bundled skill in Hermes Agent that lets you manage macOS Reminders through the terminal using remindctl. Tasks sync across all Apple devices via iCloud. Reach for this when a user asks to create a personal to-do with a due date that should appear on their iPhone or iPad.

What it does

This skill wraps remindctl, a command-line tool that talks directly to the Reminders app on macOS. You can view reminders filtered by date or list, create new ones with due dates and alarms, mark them complete, or delete them. Output can be plain text, TSV, or JSON, which makes it easy to script or integrate into larger workflows.

Before you start

• You need a Mac with the Reminders app installed and signed into iCloud.
• Install remindctl with Homebrew:

brew install steipete/tap/remindctl

• The first time you run a remindctl command, macOS will prompt you to grant Reminders permission. Accept it.
• Verify the tool is authorized:

remindctl status

If it reports an issue, run:

remindctl authorize

View reminders

These commands show reminders from different time windows. No flags needed.

remindctl                    # Today's reminders
remindctl today              # Today
remindctl tomorrow           # Tomorrow
remindctl week               # This week
remindctl overdue            # Past due
remindctl all                # Everything
remindctl 2026-01-04         # Specific date

Manage lists

Reminders are organized into lists. You can view, create, and delete them.

remindctl list               # List all lists
remindctl list Work          # Show specific list
remindctl list Projects --create    # Create list
remindctl list Work --delete        # Delete list

Create reminders

The simplest form is just a title. You can also add a list, due date, and alarm.

remindctl add "Buy milk"
remindctl add --title "Call mom" --list Personal --due tomorrow
remindctl add --title "Meeting prep" --due "2026-02-15 09:00"

Due time vs alarm / early nudge

--due and --alarm are separate fields in EventKit. --due sets the reminder's due date. --alarm sets when the notification fires. If you only set --due, the system may default the alarm to the same time. Pass --alarm explicitly when the user wants a notification before the due time.

For a reminder due at 2:00 PM with a notification 30 minutes earlier:

remindctl add --title "Hairdresser" --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"

To edit an existing reminder:

remindctl edit 87354 --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"

A common gotcha: the Reminders UI may show or group the item by the alarm time because that is when the notification fires. Verify with JSON instead of assuming the due time moved:

remindctl today --json

Expected shape:

• dueDate: actual due time
• alarmDate: notification / early nudge time

Apple's public EKReminder docs list only reminder-specific properties. Alarm support comes from inherited EKCalendarItem behavior exposed by remindctl's --alarm flag.

Complete / delete

You need the reminder's ID. You can get it from the --json output or the default plain view.

remindctl complete 1 2 3          # Complete by ID
remindctl delete 4A83 --force     # Delete by ID

Output formats

remindctl today --json       # JSON for scripting
remindctl today --plain      # TSV format
remindctl today --quiet      # Counts only

Date formats

Accepted by --due and date filters:

• today, tomorrow, yesterday
• YYYY-MM-DD
• YYYY-MM-DD HH:mm
• ISO 8601 (2026-01-04T12:34:56Z)

When not to use it

• Scheduling agent alerts: use the cronjob tool instead.
• Calendar events: use Apple Calendar or Google Calendar.
• Project task management: use GitHub Issues, Notion, or similar.
• If the user says "remind me" but means an agent alert: clarify first.

Limits and gotchas

• The Reminders UI may group items by alarm time, not due time. Always check --json output to confirm.
• --alarm is not a standard EKReminder property; it comes from the inherited EKCalendarItem behavior. remindctl exposes it, but be aware it's not part of the reminder-specific API.
• Deleting requires the --force flag.

What pairs with this

This skill is part of the Apple category in Hermes Agent. Related skills include Apple Calendar and Apple Notes. For agent-level scheduling, see the cronjob tool.