Rem CLI

rem — macOS Reminders from the terminal

rem is a single-binary Go CLI that reads and writes the Apple Reminders database in under 200ms via EventKit (cgo). Every rem invocation is fast and safe to run.

Current time (do not guess, use these values)

• Today: !date +"%A, %B %-d, %Y"
• ISO date: !date +"%Y-%m-%d"
• Local time: !date +"%H:%M %Z"
• Day of week: !date +"%A"
• Tomorrow (ISO): !date -v+1d +"%Y-%m-%d"
• Next Friday (ISO, always forward): !date -v+1d -v+fri +"%Y-%m-%d"

When the user says relative dates like "tomorrow", "next friday", "end of week", or "last tuesday", resolve them against the values above before calling rem. Don't ask the user "what is today" and don't guess from training data.

rem's --due flag accepts natural language directly (see references/dates.md), so in many cases you can pass the user's phrase through verbatim. But if the user asks something ambiguous ("what was I supposed to do yesterday?"), use the ISO date above and query rem with --due-before / --due-after against an exact date.

When to use this skill

Use rem any time the user wants to:

• Add, list, search, complete, or delete macOS Reminders
• Summarize "what's due today" / "what's overdue" / "what's coming up"
• Capture quick tasks from natural language ("remind me to call dentist tomorrow")
• Move reminders between lists, reprioritize, or add URLs and notes
• Export reminders to JSON / CSV, or import them back
• Manage reminder lists (create, rename, delete)

Do NOT use rem for:

• Calendar events (use ical if available, or AppleScript with Calendar.app)
• Other Apple apps (Notes, Messages, Mail)

Quick decision tree

For full flag details on any command, load references/commands.md.

Batch everything into one tool call

Every rem invocation is <200ms, so the expensive part is YOUR round trip, not the command. Two rules:

1. Multiple IDs, one command. complete, uncomplete, flag, unflag, and delete all accept multiple IDs: rem complete AB12 CD34 EF56. Never loop one ID per call.
2. Multiple commands, one Bash call. When answering one question needs several rem reads (or independent writes), chain them with ; and header markers in a single Bash invocation — never run them as separate tool calls. See the daily briefing pattern below.

Output formats (always set one when scripting)

Every read command supports -o table|json|plain. Default is table (colored ASCII). When piping to another tool, into a script, or when you need to parse the result, use -o json:

rem today -o json | jq '.[] | .name'
rem overdue -o json | jq 'length'
rem list --incomplete --list Work -o json

NO_COLOR=1 disables colors. REM_NO_UPDATE_CHECK=1 disables the background update check (set it when scripting to avoid stray output).

Short IDs

rem displays the first 8 characters of each reminder's UUID as its "short ID" (e.g. AB12CD34). You can pass any unique prefix to commands — rem complete AB1 works as long as it matches exactly one reminder. Prefer short IDs when showing reminder IDs back to the user.

Notifications default to ON

When --due is set on rem add, rem auto-attaches an alarm at the due time. This matches Apple Reminders.app behavior. Do NOT pass --remind-me 0m to enable notifications — that's already the default when --due is set.

• rem add "Review PR" --due tomorrow → notifies at tomorrow 9 AM (default due time)
• rem add "Review PR" --due "tomorrow 2pm" --remind-me 15m → notifies 15 minutes before
• rem add "Groceries" --due tomorrow --silent → due date, no notification (checklist-style)

Full detail: references/commands.md rem add section.

Location reminders take coordinates, not addresses

--location "lat,lng" attaches a geofence trigger that fires on arrival by default; add --on-leave for departure, --radius <meters> to widen the fence (0 = system minimum). rem does NO geocoding — you must supply decimal coordinates:

• Well-known places (landmarks, chains' flagship stores, cities): use coordinates you know.
• Personal places ("the office", "mom's house", "my gym"): ask the user for the address or coordinates — never guess.

rem add "Buy milk" --location "37.3318,-122.0312" --radius 200          # on arrival
rem update AB12 --location "37.7749,-122.4194" --on-leave               # on departure
rem update AB12 --location none                                         # remove geofence only

A reminder can have both a due date and a location. --remind-me and --location manage separate alarm buckets — clearing one never touches the other.

URLs go in the native Reminders.app URL field

When the user wants a link attached to a reminder, pass it via --url. rem writes to the real Reminders.app URL field (not the notes body), so the link shows in the Reminders.app UI with Apple's native link card rendering. Clear a URL with --url "".

rem add "Review spec" --due friday --url https://example.com/spec.pdf
rem update AB12 --url https://github.com/org/repo/pull/42
rem update AB12 --url ""    # clear