Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openclaw--remindctl/badge.svg)](/listings/openclaw--remindctl)

HTML

<a href="/listings/openclaw--remindctl"><img src="/api/listings/openclaw--remindctl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. ---
  2. name: apple-reminders
  3. 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."
  4. homepage: https://github.com/openclaw/remindctl
  5. ---
  6. # Apple Reminders
  7. Use `remindctl` for Apple Reminders on macOS. It uses Apple's public EventKit APIs, so changes sync through the normal Reminders/iCloud path.
  8. ## Prerequisites
  9. - macOS 14+ with Reminders.app
  10. - `remindctl` installed and available on `PATH`
  11. - Install with `brew install steipete/tap/remindctl`
  12. - Reminders access for the terminal app that runs `remindctl`
  13. - Use `remindctl status` to check permission state before mutating data
  14. ## Use This Skill When
  15. - The user wants to manage Apple Reminders from the terminal
  16. - The user asks for reminders, reminder lists, due dates, completion, deletion, or permission status
  17. - The user wants reminders that appear on iPhone, iPad, or Mac via Apple Reminders
  18. ## Do Not Use This Skill When
  19. - The user wants a non-Reminders agent alert, cron job, or timed chatbot reminder
  20. - The user wants calendar events instead of reminders
  21. - The user needs native Reminders sections, tags, smart lists, attachments, or Apple's private "Urgent" toggle
  22. ## Current Command Model
  23. - `remindctl` defaults to `show today`
  24. - `show` accepts filters: `today`, `tomorrow`, `week`, `overdue`, `upcoming`, `open`, `completed`, `all`, or a date string
  25. - `show --list <name>` limits a view to one list
  26. - `list` shows all lists with no arguments, or reminders in one or more named lists
  27. - `add` creates a reminder
  28. - `edit` updates a reminder by index or ID prefix
  29. - `complete` marks reminders complete
  30. - `delete` removes reminders
  31. - `status` reports Reminders authorization without prompting
  32. - `authorize` requests permission when possible
  33. ## Helpful Aliases
  34. - `lists` and `ls` map to `list`
  35. - `rm` maps to `delete`
  36. - `done` maps to `complete`
  37. ## Output And Flags
  38. - `--json`, `-j`, `--json-output`, and `--jsonOutput` emit JSON
  39. - `--plain` emits stable tab-separated output
  40. - `--quiet` emits minimal output
  41. - `--no-color` disables colored output
  42. - `--no-input` disables interactive prompts
  43. Prefer `--json` when another step needs machine-readable data. JSON can include EventKit metadata such as `creationDate`, `lastModifiedDate`, `url`, `alarmDate`, `locationTrigger`, and `recurrenceRule`.
  44. ## Reading Reminder Data
  45. - Use `remindctl today --json` or `remindctl show --json` to inspect reminders
  46. - Use `remindctl open --json` for all incomplete reminders, including reminders without due dates
  47. - Use `remindctl list --json` to inspect lists
  48. - Use `remindctl list Work Errands --json` to inspect multiple lists together
  49. - Use `remindctl status --json` to inspect authorization state
  50. - Reminder IDs and display indexes come from `show` output; `complete`, `delete`, and `edit` accept either an index or an ID prefix
  51. ## Creating Reminders
  52. `add` accepts the title as a positional argument or via `--title`, but not both.
  53. Important options:
  54. - `--list <name>` choose the target list
  55. - `--due <date>` set the due date
  56. - `--alarm <date>` set the alarm date
  57. - `--notes <text>` add notes
  58. - `--url <url>` set the dedicated URL field
  59. - `--repeat <rule>` set simple recurrence
  60. - `--priority <none|low|medium|high>` set priority
  61. - `--location <address>` create a location trigger
  62. - `--radius <meters>` adjust geofence radius
  63. - `--leaving` trigger on leaving instead of arriving
  64. 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`.
  65. Use `--location` whenever using `--radius` or `--leaving`; those flags are invalid on their own.
  66. ## Editing Reminders
  67. `edit` can update:
  68. - `--title`
  69. - `--list`
  70. - `--due` or `--clear-due`
  71. - `--alarm` or `--clear-alarm`
  72. - `--notes`
  73. - `--url` or `--clear-url`
  74. - `--repeat` or `--no-repeat`
  75. - `--priority`
  76. - `--complete` or `--incomplete`
  77. 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`.
  78. 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.
  79. ## Dates
  80. Accepted date inputs:
  81. - `today`, `tomorrow`, `yesterday`
  82. - `YYYY-MM-DD`
  83. - `YYYY-MM-DD HH:mm`
  84. - ISO 8601 with timezone, such as `2026-01-03T12:34:56Z`
  85. - Local ISO 8601 without timezone, such as `2026-01-03T12:34:56`
  86. Rules:
  87. - Date-only inputs create all-day reminders
  88. - Date-time inputs create timed reminders
  89. - Timed due reminders get a notification alarm at the due time unless `--alarm` overrides it
  90. - Due-only edits preserve every alarm; explicit alarm edits preserve relative and location-based alarms
  91. If the user provides only a calendar date, prefer a date-only value instead of inventing a time.
  92. Supported repeat values:
  93. - `daily`, `weekly`, `biweekly`, `monthly`, `yearly`
  94. - `every N days/weeks/months/years`
  95. ## Lists
  96. - `remindctl list` prints all lists with reminder and overdue counts
  97. - `remindctl list <name...>` prints reminders in one or more lists
  98. - `remindctl list <name> --create` creates the list if missing
  99. - `remindctl list <name> --delete` deletes the list
  100. - `remindctl list <name> --rename <new-name>` renames the list
  101. - `remindctl list <name> --force` skips confirmation for destructive list deletion
  102. - Create, delete, and rename accept one list name only
  103. ## Completion And Deletion
  104. - `complete` and `delete` require one or more IDs or indexes
  105. - `delete` prompts for confirmation unless `--force` or `--no-input` suppresses it
  106. - `complete` supports `--dry-run`
  107. - `delete` supports `--dry-run`
  108. ## Permissions
  109. Use `remindctl status` first when permission state matters.
  110. - `status` never prompts
  111. - `authorize` triggers the system prompt when the state is `notDetermined`
  112. - If access is denied, direct the user to `System Settings > Privacy & Security > Reminders`
  113. - If the prompt does not appear, the current workaround is to run:
  114. ```bash
  115. osascript -e 'tell application "Reminders" to get name of reminders'
  116. ```
  117. When running over SSH, grant access on the Mac that actually runs `remindctl`.
  118. ## Response Discipline
  119. - Confirm the reminder title, list, and due date before creating it if any of them are ambiguous
  120. - Use the exact command syntax shown by the current implementation
  121. - Do not reuse stale guidance about deleting and recreating reminders to move them between lists
  122. - Do not assume a fixed default list name
  123. - 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.

  1. # remindctl
  2. ![remindctl banner](docs/assets/readme-banner.jpg)
  3. Fast command-line access to Apple Reminders on macOS.
  4. `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.
  5. Docs: https://remindctl.sh
  6. ## Install
  7. ### Homebrew
  8. ```bash
  9. brew install steipete/tap/remindctl
  10. ```
  11. ### From Source
  12. ```bash
  13. pnpm install
  14. pnpm build
  15. # binary at ./bin/remindctl
  16. ```
  17. ## Requirements
  18. - macOS 14+ (Sonoma or later)
  19. - Swift 6.2+ when building from source
  20. - Full Reminders access for the terminal app that runs `remindctl`
  21. ## Quick Start
  22. ```bash
  23. remindctl add "Buy milk"
  24. remindctl add "Call mom" --list Personal --due tomorrow
  25. remindctl add "Meeting" --due "2026-01-03 09:00" --alarm "2026-01-03 08:55"
  26. remindctl add "Buy headphones" --url "https://example.com/product"
  27. remindctl today
  28. remindctl overdue
  29. remindctl open
  30. remindctl list Work Errands
  31. remindctl list --list-id 7A12
  32. remindctl search "milk"
  33. remindctl info 1
  34. remindctl doctor --for-agent
  35. remindctl export --list Work --export-format csv
  36. remindctl link 1
  37. remindctl edit 1 --title "New title" --due 2026-01-04
  38. remindctl edit 1 --url "https://example.com/product" # or --clear-url to remove it
  39. remindctl complete 1 2 3
  40. remindctl delete 4A83 --force
  41. ```
  42. 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.
  43. Indexes such as `1` come from the default reminder listing. Most commands also accept an ID prefix such as `4A83`.
  44. ## Commands
  45. | Command | Purpose |
  46. | --- | --- |
  47. | `remindctl` / `remindctl today` | Show today's reminders |
  48. | `remindctl show <filter>` | Show reminders by filter or date |
  49. | `remindctl search <query>` | Search incomplete reminder titles, notes, and URLs |
  50. | `remindctl info <id>` | Show detailed reminder metadata |
  51. | `remindctl list` | Show reminder lists |
  52. | `remindctl list <name...>` | Show reminders from one or more lists |
  53. | `remindctl export` | Export reminders as JSON or CSV |
  54. | `remindctl link <id>` | Print a best-effort Reminders deep link |
  55. | `remindctl open <id>` | Open a reminder or list in Reminders.app |
  56. | `remindctl doctor` | Diagnose permissions and read-only rich-store access |
  57. | `remindctl add <title>` | Create a reminder |
  58. | `remindctl edit <id>` | Edit a reminder by index or ID prefix |
  59. | `remindctl complete <id...>` | Mark reminders complete |
  60. | `remindctl delete <id...>` | Delete reminders |
  61. | `remindctl status` | Show Reminders permission status |
  62. | `remindctl authorize` | Request Reminders permission when macOS allows it |
  63. Run `remindctl <command> --help` for the full option list. Unexpected extra arguments are rejected; quote multi-word titles and list names.
  64. ## Showing Reminders
  65. Common filters:
  66. ```bash
  67. remindctl today
  68. remindctl tomorrow
  69. remindctl week
  70. remindctl overdue
  71. remindctl upcoming
  72. remindctl open
  73. remindctl completed
  74. remindctl all
  75. remindctl 2026-01-03
  76. ```
  77. Search titles, notes, and URLs:
  78. ```bash
  79. remindctl search "milk"
  80. remindctl search "invoice" --list Work
  81. remindctl search "project" --completed --json
  82. ```
  83. Standard search output includes stable reminder IDs instead of numeric indexes.
  84. Inspect one reminder:
  85. ```bash
  86. remindctl info 1
  87. remindctl info 4A83 --json
  88. ```
  89. Limit a view to one list:
  90. ```bash
  91. remindctl show overdue --list Work
  92. remindctl show overdue --list-id 7A12
  93. ```
  94. Show multiple lists together:
  95. ```bash
  96. remindctl list Work Errands
  97. ```
  98. ## Lists
  99. ```bash
  100. remindctl list
  101. remindctl list Work
  102. remindctl list Projects --create
  103. remindctl list Work --rename Office
  104. remindctl list OldList --delete --force
  105. ```
  106. Mutating list operations accept one list name. Read-only list views can accept multiple names.
  107. 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`.
  108. Exact list targeting:
  109. ```bash
  110. remindctl list --list-id 7A12
  111. remindctl add "Review notes" --list-id 7A12
  112. remindctl edit 4A83 --list-id 7A12
  113. remindctl list --list-id 7A12 --rename Archive
  114. remindctl list --list-id 7A12 --delete --force
  115. ```
  116. ## Dates And Due Times
  117. Accepted by `--due` and date filters:
  118. - `today`, `tomorrow`, `yesterday`
  119. - `YYYY-MM-DD`
  120. - `YYYY-MM-DD HH:mm`
  121. - ISO 8601 with timezone, such as `2026-01-03T12:34:56Z`
  122. - Local ISO 8601 without timezone, such as `2026-01-03T12:34:56`
  123. Date-only due values create all-day reminders. Date-time values create timed reminders.
  124. 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.
  125. ## Alarms
  126. Timed due reminders automatically get an EventKit notification alarm at the due time. Use `--alarm` to choose a different alarm time.
  127. ```bash
  128. remindctl add "Meeting" --due "2026-01-03 09:00" --alarm "2026-01-03 08:55"
  129. remindctl edit 4A83 --alarm "2026-01-03 08:55"
  130. remindctl edit 4A83 --clear-alarm
  131. ```
  132. This is public EventKit alarm support. Apple's private Reminders "Urgent" toggle is not exposed by EventKit.
  133. 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.
  134. ## Repeat
  135. Use `--repeat` with `add` or `edit` for simple recurrence:
  136. ```bash
  137. remindctl add "Take vitamins" --due tomorrow --repeat daily
  138. remindctl add "Water filter" --due "2026-09-13" --repeat "every 6 months"
  139. remindctl edit 4A83 --repeat weekly
  140. remindctl edit 4A83 --no-repeat
  141. ```
  142. Supported repeat values:
  143. - `daily`, `weekly`, `biweekly`, `monthly`, `yearly`
  144. - `every N days/weeks/months/years`
  145. ## Location Triggers
  146. 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.
  147. ```bash
  148. remindctl add "Check mailbox" --location "1 Apple Park Way, Cupertino, CA"
  149. remindctl add "Lock up" --location "Home" --leaving
  150. remindctl add "Get groceries" --location "123 Main St" --radius 200
  151. ```
  152. Location triggers use EventKit and CoreLocation geocoding. They may depend on system location services and network availability.
  153. Geofence radii must be finite, positive numbers of meters.
  154. ## Output
  155. Global output flags:
  156. - `--json` emits machine-readable JSON.
  157. - `--plain` emits stable tab-separated lines.
  158. - `--format table` emits tabular output for scan-heavy commands.
  159. - `--quiet` emits minimal output, usually counts or nothing.
  160. - `--no-color` disables colored output.
  161. - `--no-input` disables interactive prompts.
  162. JSON includes public EventKit metadata when available:
  163. - `creationDate`
  164. - `lastModifiedDate`
  165. - `url`
  166. - `alarmDate`
  167. - `locationTrigger`
  168. - `recurrenceRule`
  169. Example:
  170. ```bash
  171. remindctl all --json
  172. remindctl today --format table
  173. remindctl list --json
  174. remindctl status --json
  175. ```
  176. ## Export, Links, And Completion
  177. ```bash
  178. remindctl export --json
  179. remindctl export --list Work --export-format csv
  180. remindctl link 1
  181. remindctl link --list-id 7A12
  182. remindctl open 1
  183. remindctl open --list Work
  184. remindctl open --list Work --app
  185. remindctl open --app
  186. remindctl completion zsh
  187. ```
  188. `link` and `open <id>` use best-effort Reminders deep links based on EventKit IDs. `open --list Work`
  189. keeps the historical open-reminders filter; add `--app` to open that list in Reminders.app.
  190. ## Permissions
  191. Check access:
  192. ```bash
  193. remindctl status
  194. remindctl doctor --for-agent
  195. ```
  196. Request access:
  197. ```bash
  198. remindctl authorize
  199. ```
  200. If macOS reports access as denied, enable the terminal app in:
  201. ```text
  202. System Settings > Privacy & Security > Reminders
  203. ```
  204. If no prompt appears, run this once from the same terminal app:
  205. ```bash
  206. osascript -e 'tell application "Reminders" to get name of reminders'
  207. ```
  208. Then allow access and rerun:
  209. ```bash
  210. remindctl status
  211. ```
  212. When running over SSH, grant access on the Mac that actually runs `remindctl`.
  213. ## EventKit Limits
  214. Reminder reads skip orphaned EventKit reminders whose calendar is missing; other reminders remain available.
  215. 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.
  216. `remindctl` intentionally sticks to public EventKit APIs. These Reminders.app features are not exposed through EventKit today:
  217. - Native Reminders sections
  218. - Native Reminders tags and smart lists
  219. - File/image attachments
  220. - Apple's private "Urgent" toggle
  221. Supporting those would require Apple to expose new public APIs or a separate non-EventKit backend.
  222. 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.
  223. ## Development
  224. Install the same checksum-verified SwiftLint 0.65.1 as CI, then run the local checks:
  225. ```bash
  226. bash scripts/install-linters.sh
  227. export PATH="$PWD/.build/linters:$PATH"
  228. make lint
  229. ```
  230. 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).
  231. The package manager is pinned in `package.json`, and `.node-version` selects the docs runtime.
  232. 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.
  233. `make check` runs the Swift tests once with coverage and retains the 90% RemindCore gate.
  234. CodeQL scans Swift with an explicit package build after dependency resolution, plus JavaScript/TypeScript and Actions.
  235. ```bash
  236. make remindctl ARGS="status" # clean build + run
  237. make check # strict lint + tests + 90% coverage gate
  238. make release-harness # credential-free release-policy mocks
  239. make macos-artifact # ad-hoc universal local candidate; never publish
  240. make release-check TAG=vX.Y.Z # validate release preflight
  241. pnpm build # release build into ./bin/remindctl
  242. ```
  243. Release steps live in [docs/RELEASING.md](docs/RELEASING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.