Metadata

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@latest

Install this skill into your agent:

# Claude Code or Codex
rem skills install

# OpenClaw
rem skills install --agent openclaw

Quick 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 stats

Command 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 eod

Supported 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 items

Batch 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
--flagged filter is slower (~3-4s) — falls back to JXA since EventKit doesn't expose flagged
List deletion may fail on some macOS versions

rem

安装技能