remindctl
cli for Apple Reminders app
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/openclaw/remindctl with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/openclaw/remindctl'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/openclaw--remindctl)HTML
<a href="/listings/openclaw--remindctl"><img src="/api/listings/openclaw--remindctl/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Homebrew
brew install steipete/tap/remindctl
From Source
pnpm install pnpm build # binary at ./bin/remindctl
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 170 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: apple-reminders
- description: "Use remindctl to inspect and manage Apple Reminders on macOS 14+, including show/list/add/edit/complete/delete/status/authorize workflows, due dates, alarms, recurrence, and location triggers."
- homepage: https://github.com/openclaw/remindctl
- ---
- # Apple Reminders
- Use `remindctl` for Apple Reminders on macOS. It uses Apple's public EventKit APIs, so changes sync through the normal Reminders/iCloud path.
- ## Prerequisites
- - macOS 14+ with Reminders.app
- - `remindctl` installed and available on `PATH`
- - Install with `brew install steipete/tap/remindctl`
- - Reminders access for the terminal app that runs `remindctl`
- - Use `remindctl status` to check permission state before mutating data
- ## Use This Skill When
- - The user wants to manage Apple Reminders from the terminal
- - The user asks for reminders, reminder lists, due dates, completion, deletion, or permission status
- - The user wants reminders that appear on iPhone, iPad, or Mac via Apple Reminders
- ## Do Not Use This Skill When
- - The user wants a non-Reminders agent alert, cron job, or timed chatbot reminder
- - The user wants calendar events instead of reminders
- - The user needs native Reminders sections, tags, smart lists, attachments, or Apple's private "Urgent" toggle
- ## Current Command Model
- - `remindctl` defaults to `show today`
- - `show` accepts filters: `today`, `tomorrow`, `week`, `overdue`, `upcoming`, `open`, `completed`, `all`, or a date string
- - `show --list <name>` limits a view to one list
- - `list` shows all lists with no arguments, or reminders in one or more named lists
- - `add` creates a reminder
- - `edit` updates a reminder by index or ID prefix
- - `complete` marks reminders complete
- - `delete` removes reminders
- - `status` reports Reminders authorization without prompting
- - `authorize` requests permission when possible
- ## Helpful Aliases
- - `lists` and `ls` map to `list`
- - `rm` maps to `delete`
- - `done` maps to `complete`
- ## Output And Flags
- - `--json`, `-j`, `--json-output`, and `--jsonOutput` emit JSON
- - `--plain` emits stable tab-separated output
- - `--quiet` emits minimal output
- - `--no-color` disables colored output
- - `--no-input` disables interactive prompts
- Prefer `--json` when another step needs machine-readable data. JSON can include EventKit metadata such as `creationDate`, `lastModifiedDate`, `url`, `alarmDate`, `locationTrigger`, and `recurrenceRule`.
- ## Reading Reminder Data
- - Use `remindctl today --json` or `remindctl show --json` to inspect reminders
- - Use `remindctl open --json` for all incomplete reminders, including reminders without due dates
- - Use `remindctl list --json` to inspect lists
- - Use `remindctl list Work Errands --json` to inspect multiple lists together
- - Use `remindctl status --json` to inspect authorization state
- - Reminder IDs and display indexes come from `show` output; `complete`, `delete`, and `edit` accept either an index or an ID prefix
- ## Creating Reminders
- `add` accepts the title as a positional argument or via `--title`, but not both.
- Important options:
- - `--list <name>` choose the target list
- - `--due <date>` set the due date
- - `--alarm <date>` set the alarm date
- - `--notes <text>` add notes
- - `--url <url>` set the dedicated URL field
- - `--repeat <rule>` set simple recurrence
- - `--priority <none|low|medium|high>` set priority
- - `--location <address>` create a location trigger
- - `--radius <meters>` adjust geofence radius
- - `--leaving` trigger on leaving instead of arriving
- If no list is provided, `remindctl` uses the Reminders app's default list. Do not assume the default is a specific list name. If the system has no default reminder list, specify `--list`.
- Use `--location` whenever using `--radius` or `--leaving`; those flags are invalid on their own.
- ## Editing Reminders
- `edit` can update:
- - `--title`
- - `--list`
- - `--due` or `--clear-due`
- - `--alarm` or `--clear-alarm`
- - `--notes`
- - `--url` or `--clear-url`
- - `--repeat` or `--no-repeat`
- - `--priority`
- - `--complete` or `--incomplete`
- Reject conflicting combinations such as `--due` with `--clear-due`, `--alarm` with `--clear-alarm`, `--url` with `--clear-url`, `--repeat` with `--no-repeat`, or `--complete` with `--incomplete`.
- Use `remindctl edit <id> --list <new-list>` to move a reminder between lists. Do not tell the user to delete and recreate the reminder for a move; the command already supports moving it directly.
- ## Dates
- Accepted date inputs:
- - `today`, `tomorrow`, `yesterday`
- - `YYYY-MM-DD`
- - `YYYY-MM-DD HH:mm`
- - ISO 8601 with timezone, such as `2026-01-03T12:34:56Z`
- - Local ISO 8601 without timezone, such as `2026-01-03T12:34:56`
- Rules:
- - Date-only inputs create all-day reminders
- - Date-time inputs create timed reminders
- - Timed due reminders get a notification alarm at the due time unless `--alarm` overrides it
- - Due-only edits preserve every alarm; explicit alarm edits preserve relative and location-based alarms
- If the user provides only a calendar date, prefer a date-only value instead of inventing a time.
- Supported repeat values:
- - `daily`, `weekly`, `biweekly`, `monthly`, `yearly`
- - `every N days/weeks/months/years`
- ## Lists
- - `remindctl list` prints all lists with reminder and overdue counts
- - `remindctl list <name...>` prints reminders in one or more lists
- - `remindctl list <name> --create` creates the list if missing
- - `remindctl list <name> --delete` deletes the list
- - `remindctl list <name> --rename <new-name>` renames the list
- - `remindctl list <name> --force` skips confirmation for destructive list deletion
- - Create, delete, and rename accept one list name only
- ## Completion And Deletion
- - `complete` and `delete` require one or more IDs or indexes
- - `delete` prompts for confirmation unless `--force` or `--no-input` suppresses it
- - `complete` supports `--dry-run`
- - `delete` supports `--dry-run`
- ## Permissions
- Use `remindctl status` first when permission state matters.
- - `status` never prompts
- - `authorize` triggers the system prompt when the state is `notDetermined`
- - If access is denied, direct the user to `System Settings > Privacy & Security > Reminders`
- - If the prompt does not appear, the current workaround is to run:
- ```bash
- osascript -e 'tell application "Reminders" to get name of reminders'
- ```
- When running over SSH, grant access on the Mac that actually runs `remindctl`.
- ## Response Discipline
- - Confirm the reminder title, list, and due date before creating it if any of them are ambiguous
- - Use the exact command syntax shown by the current implementation
- - Do not reuse stale guidance about deleting and recreating reminders to move them between lists
- - Do not assume a fixed default list name
- - Do not promise unsupported private Reminders.app features; `remindctl` intentionally stays on public EventKit APIs
README.md · README · 332 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # remindctl
- 
- Fast command-line access to Apple Reminders on macOS.
- `remindctl` is for scripts, agents, and terminal workflows that need to read and update the same reminders you see in Reminders.app. It uses Apple's public EventKit APIs, so reminders keep syncing through the normal system/iCloud path.
- Docs: https://remindctl.sh
- ## Install
- ### Homebrew
- ```bash
- brew install steipete/tap/remindctl
- ```
- ### From Source
- ```bash
- pnpm install
- pnpm build
- # binary at ./bin/remindctl
- ```
- ## Requirements
- - macOS 14+ (Sonoma or later)
- - Swift 6.2+ when building from source
- - Full Reminders access for the terminal app that runs `remindctl`
- ## Quick Start
- ```bash
- remindctl add "Buy milk"
- remindctl add "Call mom" --list Personal --due tomorrow
- remindctl add "Meeting" --due "2026-01-03 09:00" --alarm "2026-01-03 08:55"
- remindctl add "Buy headphones" --url "https://example.com/product"
- remindctl today
- remindctl overdue
- remindctl open
- remindctl list Work Errands
- remindctl list --list-id 7A12
- remindctl search "milk"
- remindctl info 1
- remindctl doctor --for-agent
- remindctl export --list Work --export-format csv
- remindctl link 1
- remindctl edit 1 --title "New title" --due 2026-01-04
- remindctl edit 1 --url "https://example.com/product" # or --clear-url to remove it
- remindctl complete 1 2 3
- remindctl delete 4A83 --force
- ```
- URLs remain stored in EventKit and are also mirrored to a `remindctl URL (managed): ...` notes line so they are visible in Reminders.app. `--clear-url` removes the EventKit value and only that managed notes line.
- Indexes such as `1` come from the default reminder listing. Most commands also accept an ID prefix such as `4A83`.
- ## Commands
- | Command | Purpose |
- | --- | --- |
- | `remindctl` / `remindctl today` | Show today's reminders |
- | `remindctl show <filter>` | Show reminders by filter or date |
- | `remindctl search <query>` | Search incomplete reminder titles, notes, and URLs |
- | `remindctl info <id>` | Show detailed reminder metadata |
- | `remindctl list` | Show reminder lists |
- | `remindctl list <name...>` | Show reminders from one or more lists |
- | `remindctl export` | Export reminders as JSON or CSV |
- | `remindctl link <id>` | Print a best-effort Reminders deep link |
- | `remindctl open <id>` | Open a reminder or list in Reminders.app |
- | `remindctl doctor` | Diagnose permissions and read-only rich-store access |
- | `remindctl add <title>` | Create a reminder |
- | `remindctl edit <id>` | Edit a reminder by index or ID prefix |
- | `remindctl complete <id...>` | Mark reminders complete |
- | `remindctl delete <id...>` | Delete reminders |
- | `remindctl status` | Show Reminders permission status |
- | `remindctl authorize` | Request Reminders permission when macOS allows it |
- Run `remindctl <command> --help` for the full option list. Unexpected extra arguments are rejected; quote multi-word titles and list names.
- ## Showing Reminders
- Common filters:
- ```bash
- remindctl today
- remindctl tomorrow
- remindctl week
- remindctl overdue
- remindctl upcoming
- remindctl open
- remindctl completed
- remindctl all
- remindctl 2026-01-03
- ```
- Search titles, notes, and URLs:
- ```bash
- remindctl search "milk"
- remindctl search "invoice" --list Work
- remindctl search "project" --completed --json
- ```
- Standard search output includes stable reminder IDs instead of numeric indexes.
- Inspect one reminder:
- ```bash
- remindctl info 1
- remindctl info 4A83 --json
- ```
- Limit a view to one list:
- ```bash
- remindctl show overdue --list Work
- remindctl show overdue --list-id 7A12
- ```
- Show multiple lists together:
- ```bash
- remindctl list Work Errands
- ```
- ## Lists
- ```bash
- remindctl list
- remindctl list Work
- remindctl list Projects --create
- remindctl list Work --rename Office
- remindctl list OldList --delete --force
- ```
- Mutating list operations accept one list name. Read-only list views can accept multiple names.
- List names resolve by exact match, case-insensitive match, then a normalized match that ignores emoji and punctuation. If a name is ambiguous, use `--list-id`.
- Exact list targeting:
- ```bash
- remindctl list --list-id 7A12
- remindctl add "Review notes" --list-id 7A12
- remindctl edit 4A83 --list-id 7A12
- remindctl list --list-id 7A12 --rename Archive
- remindctl list --list-id 7A12 --delete --force
- ```
- ## Dates And Due Times
- Accepted by `--due` and date filters:
- - `today`, `tomorrow`, `yesterday`
- - `YYYY-MM-DD`
- - `YYYY-MM-DD HH:mm`
- - ISO 8601 with timezone, such as `2026-01-03T12:34:56Z`
- - Local ISO 8601 without timezone, such as `2026-01-03T12:34:56`
- Date-only due values create all-day reminders. Date-time values create timed reminders.
- Absolute dates must contain a valid calendar date, time, and offset; invalid dates and trailing text are rejected. Unpadded month/day/time fields and year-first `/` or `.` separators remain accepted. Legacy `MM/dd/yyyy` and `dd-MM-yy`/`dd-MM-yyyy` inputs retain their explicit month/day order.
- ## Alarms
- Timed due reminders automatically get an EventKit notification alarm at the due time. Use `--alarm` to choose a different alarm time.
- ```bash
- remindctl add "Meeting" --due "2026-01-03 09:00" --alarm "2026-01-03 08:55"
- remindctl edit 4A83 --alarm "2026-01-03 08:55"
- remindctl edit 4A83 --clear-alarm
- ```
- This is public EventKit alarm support. Apple's private Reminders "Urgent" toggle is not exposed by EventKit.
- Changing or clearing only the due date leaves every alarm unchanged. Explicit `--alarm` and `--clear-alarm` operations replace or clear absolute alarms while preserving relative and location-based alarms.
- ## Repeat
- Use `--repeat` with `add` or `edit` for simple recurrence:
- ```bash
- remindctl add "Take vitamins" --due tomorrow --repeat daily
- remindctl add "Water filter" --due "2026-09-13" --repeat "every 6 months"
- remindctl edit 4A83 --repeat weekly
- remindctl edit 4A83 --no-repeat
- ```
- Supported repeat values:
- - `daily`, `weekly`, `biweekly`, `monthly`, `yearly`
- - `every N days/weeks/months/years`
- ## Location Triggers
- Use `--location` on `add` to create an arriving geofence trigger. Add `--leaving` to trigger when leaving, and `--radius` to customize the geofence radius in meters.
- ```bash
- remindctl add "Check mailbox" --location "1 Apple Park Way, Cupertino, CA"
- remindctl add "Lock up" --location "Home" --leaving
- remindctl add "Get groceries" --location "123 Main St" --radius 200
- ```
- Location triggers use EventKit and CoreLocation geocoding. They may depend on system location services and network availability.
- Geofence radii must be finite, positive numbers of meters.
- ## Output
- Global output flags:
- - `--json` emits machine-readable JSON.
- - `--plain` emits stable tab-separated lines.
- - `--format table` emits tabular output for scan-heavy commands.
- - `--quiet` emits minimal output, usually counts or nothing.
- - `--no-color` disables colored output.
- - `--no-input` disables interactive prompts.
- JSON includes public EventKit metadata when available:
- - `creationDate`
- - `lastModifiedDate`
- - `url`
- - `alarmDate`
- - `locationTrigger`
- - `recurrenceRule`
- Example:
- ```bash
- remindctl all --json
- remindctl today --format table
- remindctl list --json
- remindctl status --json
- ```
- ## Export, Links, And Completion
- ```bash
- remindctl export --json
- remindctl export --list Work --export-format csv
- remindctl link 1
- remindctl link --list-id 7A12
- remindctl open 1
- remindctl open --list Work
- remindctl open --list Work --app
- remindctl open --app
- remindctl completion zsh
- ```
- `link` and `open <id>` use best-effort Reminders deep links based on EventKit IDs. `open --list Work`
- keeps the historical open-reminders filter; add `--app` to open that list in Reminders.app.
- ## Permissions
- Check access:
- ```bash
- remindctl status
- remindctl doctor --for-agent
- ```
- Request access:
- ```bash
- remindctl authorize
- ```
- If macOS reports access as denied, enable the terminal app in:
- ```text
- System Settings > Privacy & Security > Reminders
- ```
- If no prompt appears, run this once from the same terminal app:
- ```bash
- osascript -e 'tell application "Reminders" to get name of reminders'
- ```
- Then allow access and rerun:
- ```bash
- remindctl status
- ```
- When running over SSH, grant access on the Mac that actually runs `remindctl`.
- ## EventKit Limits
- Reminder reads skip orphaned EventKit reminders whose calendar is missing; other reminders remain available.
- If a calendar is missing after `add`, `edit`, or `complete` saves a reminder, the command reports `Reminder is missing a calendar` instead of crashing. The change has already been saved; check Reminders.app before retrying.
- `remindctl` intentionally sticks to public EventKit APIs. These Reminders.app features are not exposed through EventKit today:
- - Native Reminders sections
- - Native Reminders tags and smart lists
- - File/image attachments
- - Apple's private "Urgent" toggle
- Supporting those would require Apple to expose new public APIs or a separate non-EventKit backend.
- Moving reminders with `edit --list` or `edit --list-id` can fail when either list is shared. If EventKit rejects the move with `com.apple.reminderkit error -3002`, move the reminder in Reminders.app, then retry any other edits. `remindctl` does not copy and delete reminders to work around this restriction because EventKit cannot preserve all Reminders.app metadata.
- ## Development
- Install the same checksum-verified SwiftLint 0.65.1 as CI, then run the local checks:
- ```bash
- bash scripts/install-linters.sh
- export PATH="$PWD/.build/linters:$PATH"
- make lint
- ```
- The version and archive checksum live in `scripts/install-linters.sh`; update them together after validating `.swiftlint.yml`. Formatting uses Apple's `swift format` from the selected Xcode toolchain (Xcode 27 in CI).
- The package manager is pinned in `package.json`, and `.node-version` selects the docs runtime.
- CI uses the Xcode 27 toolchain on `xcode-27`, builds both release architectures with a macOS 14 deployment target, and runs the universal CLI natively and under Rosetta. Swift CodeQL remains on macOS 26 until its tracer supports macOS 27.
- `make check` runs the Swift tests once with coverage and retains the 90% RemindCore gate.
- CodeQL scans Swift with an explicit package build after dependency resolution, plus JavaScript/TypeScript and Actions.
- ```bash
- make remindctl ARGS="status" # clean build + run
- make check # strict lint + tests + 90% coverage gate
- make release-harness # credential-free release-policy mocks
- make macos-artifact # ad-hoc universal local candidate; never publish
- make release-check TAG=vX.Y.Z # validate release preflight
- pnpm build # release build into ./bin/remindctl
- ```
- Release steps live in [docs/RELEASING.md](docs/RELEASING.md).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.