- name
- rem
- description
- Manages macOS Reminders from the terminal using the rem CLI. Creates, lists, updates, completes, deletes, searches, and exports reminders and lists. Supports natural language due dates, filtering, import/export, and multiple output formats. Use when the user wants to interact with Apple Reminders via command line, automate reminder workflows, or build scripts around macOS Reminders.
- metadata
- author
- BRO3886
- version
- 0.7.0
- compatibility
- Requires macOS with Reminders.app. Requires Xcode Command Line Tools for building from source.
rem — CLI for macOS Reminders
A Go CLI that wraps macOS Reminders. Sub-200ms reads via cgo + EventKit. Single binary, no dependencies at runtime.
Installation
# macOS (recommended)
curl -fsSL https://rem.sidv.dev/install | bash
# Or via Go
go install github.com/BRO3886/rem/cmd/rem@latestInstall this skill into your agent:
# Claude Code or Codex
rem skills install
# OpenClaw
rem skills install --agent openclawQuick Start
# See all lists with reminder counts
rem lists --count
# Add a reminder with natural language date
rem add "Buy groceries" --list Personal --due tomorrow --priority high
# List incomplete reminders in a list
rem list --list Work --incomplete
# Search across all reminders
rem search "meeting"
# Complete a reminder by short ID
rem complete abc12345
# View stats
rem statsCommand Reference
Reminder CRUD
| Command | Aliases | Description |
|---|---|---|
rem add | create, new | Create a reminder |
rem list | ls | List reminders with filters |
rem show | get | Show full details of one reminder |
rem update | edit | Update reminder properties |
rem delete | rm, remove | Delete a reminder |
rem complete | done | Mark reminder complete |
rem uncomplete | — | Mark reminder incomplete |
rem flag | — | Flag a reminder |
rem unflag | — | Remove flag |
List Management
| Command | Aliases | Description |
|---|---|---|
rem lists | — | Show all lists |
rem list-mgmt create | lm new | Create a list |
rem list-mgmt rename | — | Rename a list |
rem list-mgmt delete | lm rm | Delete a list |
Search & Analytics
| Command | Description |
|---|---|
rem search <query> | Search title and notes |
rem stats | Show statistics and per-list breakdown |
rem overdue | Show overdue reminders |
rem upcoming | Show reminders due in next N days (default: 7) |
Import/Export
| Command | Description |
|---|---|
rem export | Export to JSON or CSV |
rem import <file> | Import from JSON or CSV file |
Skills & Other
| Command | Description |
|---|---|
rem skills install | Install rem skill for AI agents |
rem skills uninstall | Uninstall rem skill from AI agents |
rem skills status | Show skill installation status |
rem interactive / rem i | Interactive menu-driven mode |
rem version | Print version |
rem completion | Generate shell completions (bash/zsh/fish) |
For full flag details on every command, see references/commands.md.
Key Concepts
Short IDs
Reminders have UUIDs like x-apple-reminder://AB12CD34-.... The CLI displays the first 8 characters as a short ID (AB12CD34). You can pass any unique prefix to commands — rem complete AB1 works if it matches exactly one reminder.
Natural Language Dates
The --due flag accepts natural language:
rem add "Call dentist" --due tomorrow
rem add "Submit report" --due "next friday at 2pm"
rem add "Quick task" --due "in 30 minutes"
rem add "Wrap up" --due eodSupported patterns: today, tomorrow, next monday, in 3 hours, eod, eow, 5pm, 2026-02-15, and more. See references/dates.md for the full list.
Priority Levels
| Level | Flag value | AppleScript value |
|---|---|---|
| High | --priority high | 1 (range 1-4) |
| Medium | --priority medium | 5 |
| Low | --priority low | 9 (range 6-9) |
| None | --priority none | 0 |
Output Formats
All read commands support -o / --output:
- table (default) — formatted table with borders
- json — machine-readable JSON
- plain — simple text, one item per line
The NO_COLOR environment variable is respected.
URL Storage
macOS Reminders has no native URL field. rem stores URLs in the notes/body field with a URL: prefix and extracts them for display.
Common Workflows
Daily review
rem overdue # Check what's past due
rem upcoming --days 1 # See today's reminders
rem list --list Work --incomplete # Focus on work itemsBatch operations with JSON
rem export --list Work --format json > backup.json
rem import backup.json --list "Work Archive"Scripting with JSON output
# Get overdue count
rem overdue -o json | jq 'length'
# List all incomplete reminder titles
rem list --incomplete -o json | jq -r '.[].name'Public Go API
For programmatic access, use go-eventkit directly:
import "github.com/BRO3886/go-eventkit/reminders"
client, _ := reminders.New()
r, _ := client.CreateReminder(reminders.CreateReminderInput{
Title: "Buy milk",
ListName: "Shopping",
Priority: reminders.PriorityHigh,
})
items, _ := client.Reminders(reminders.WithCompleted(false))See go-eventkit docs for the full API surface.
Limitations
- macOS only — requires EventKit framework and
osascript - No tags, subtasks, or recurrence — not exposed by EventKit/AppleScript
--flaggedfilter is slower (~3-4s) — falls back to JXA since EventKit doesn't expose flagged- List deletion may fail on some macOS versions