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