apple-reminders

name	apple-reminders
description	Manage Apple Reminders from the terminal via the remindctl CLI — add, list, complete, and set due dates/alarms that sync to the user's iPhone and iPad over iCloud. macOS only. Use when the user mentions Reminders or wants a to-do on their Apple devices.

Apple Reminders

Use remindctl to manage Apple Reminders directly from the terminal. Tasks sync across all Apple devices via iCloud.

Prerequisites

• macOS with Reminders.app
• Install: brew install steipete/tap/remindctl
• Grant Reminders permission when prompted
• Check: remindctl status / Request: remindctl authorize

When to Use

• User mentions "reminder" or "Reminders app"
• Creating personal to-dos with due dates that sync to iOS
• Managing Apple Reminders lists
• User wants tasks to appear on their iPhone/iPad

When NOT to Use

• Scheduling Stella alerts/notifications → use Stella's Schedule instead
• Calendar events → use Apple Calendar or Google Calendar
• Project task management → use GitHub Issues, Notion, etc.
• If user says "remind me" but means a Stella alert → clarify first

Quick Reference

View Reminders

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

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

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 different fields:

• --due sets the reminder's due date/time.
• --alarm sets the EventKit alarm/notification trigger. Timed due reminders may default to an alarm at the due time, but pass --alarm explicitly when the user asks for an earlier nudge.

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"

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

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)

Rules

1. When user says "remind me", clarify: Apple Reminders (syncs to phone) vs a Stella scheduled alert
2. Always confirm reminder content and due date before creating
3. Use --json for programmatic parsing