[BREAKGLASS] cli for Apple Reminders app

Go to file

Peter Steinberger 50cc4f56ba feat: expose reminder creation date Co-authored-by: Travis Irby <travis.irby@gmail.com>		2026-05-04 05:42:54 +01:00
.github/workflows	docs: add release process and notarization script	2026-01-04 01:53:56 +01:00
docs	feat: add `open` filter to show all incomplete reminders	2026-05-04 05:27:54 +01:00
scripts	docs: add release process and notarization script	2026-01-04 01:53:56 +01:00
Sources	feat: expose reminder creation date	2026-05-04 05:42:54 +01:00
Tests	feat: expose reminder creation date	2026-05-04 05:42:54 +01:00
.gitignore	feat: initial remindctl cli	2026-01-03 07:14:56 +01:00
.swift-format	feat: initial remindctl cli	2026-01-03 07:14:56 +01:00
.swiftlint.yml	feat: initial remindctl cli	2026-01-03 07:14:56 +01:00
CHANGELOG.md	feat: expose reminder creation date	2026-05-04 05:42:54 +01:00
LICENSE	Initial commit	2026-01-03 07:14:05 +01:00
Makefile	feat: add permissions commands and dev tasks	2026-01-03 13:20:56 +01:00
package.json	chore: bump version to 0.2.0	2026-05-04 05:24:29 +01:00
Package.resolved	chore: update Commander dependency	2026-05-04 02:04:22 +01:00
Package.swift	feat: initial remindctl cli	2026-01-03 07:14:56 +01:00
README.md	feat: add `open` filter to show all incomplete reminders	2026-05-04 05:27:54 +01:00
version.env	chore: bump version to 0.2.0	2026-05-04 05:24:29 +01:00

README.md

remindctl

Forget the app, not the task ✅

Fast CLI for Apple Reminders on macOS.

Install

Homebrew (Home Pro)

brew install steipete/tap/remindctl

From source

pnpm install
pnpm build
# binary at ./bin/remindctl

Development

make remindctl ARGS="status"   # clean build + run
make check                     # lint + test + coverage gate

Requirements

macOS 14+ (Sonoma or later)
Swift 6.2+
Reminders permission (System Settings → Privacy & Security → Reminders)

Usage

remindctl                      # show today (default)
remindctl today                 # show today
remindctl tomorrow              # show tomorrow
remindctl week                  # show this week
remindctl overdue               # overdue
remindctl upcoming              # upcoming
remindctl open                  # all incomplete reminders
remindctl completed             # completed
remindctl all                   # all reminders
remindctl 2026-01-03            # specific date

remindctl list                  # lists
remindctl list Work             # show list
remindctl list Work --rename Office
remindctl list Work --delete
remindctl list Projects --create

remindctl add "Buy milk"
remindctl add --title "Call mom" --list Personal --due tomorrow
remindctl edit 1 --title "New title" --due 2026-01-04
remindctl list Work Errands       # show reminders from multiple lists
remindctl complete 1 2 3
remindctl delete 4A83 --force
remindctl status                # permission status
remindctl authorize             # request permissions

Output formats

--json emits JSON arrays/objects.
--plain emits tab-separated lines.
--quiet emits counts only.

Date formats

Accepted by --due and filters:

today, tomorrow, yesterday
YYYY-MM-DD
YYYY-MM-DD HH:mm
ISO 8601 (2026-01-03T12:34:56Z)
Local ISO 8601 without timezone (2026-01-03T12:34:56)

Date-only due inputs create all-day reminders; date-time inputs create timed reminders.

Permissions

Run remindctl authorize to trigger the system prompt. If access is denied, enable Terminal (or remindctl) in System Settings → Privacy & Security → Reminders. If running over SSH, grant access on the Mac that runs the command. If no prompt appears in your terminal app, run:

osascript -e 'tell application "Reminders" to get name of reminders'

Then allow access and rerun remindctl status.