reminders-cli: a command line for the macOS Reminders app

The reminder database, reachable from a shell

The macOS Reminders app is a fine application and an awkward one to script. Everything lives in a private store that Apple does not expose a command line for, so a task that needs a reminder created on a schedule, or a list checked from a script, ends up driving the GUI. reminders-cli is a simple CLI for interacting with OS X reminders, written in Swift, and it exists to close that gap. The command surface is small and imperative: show-lists, show, show-all, add, edit, complete, uncomplete, delete, plus help. For a person who lives in the terminal, that is the difference between a reminder being part of a script and being a thing you click on. The audience is macOS users with a shell habit, not teams building a shared task system.

Listing lists, then listing the items in one

The read side starts with the lists themselves:

$ reminders show-lists
Soon
Eventually

Once you know the list name, the items in it are printed with numeric indices, and those indices are what every mutating command expects:

$ reminders show Soon
0 Write README
1 Ship reminders-cli

That indexing is the design decision to be aware of, because it makes the tool scriptable but also makes indices positional. If the list changes underneath you, index 0 may no longer be the item you meant. The show-all variant exists for the case where you do not care which list an item is in, and both accept a date filter, so you can ask for what is due today and optionally include what is overdue:

$ reminders show-all --due-date today --include-overdue
0: Ship reminders-cli (2 days ago)
1: Contribute to open source (in 3 hours)

The filter accepts a named date such as today or an explicit one such as 2025-02-16.

Adding items with due dates and priorities

Adding is a single command with optional flags. The list comes first, then the text, and the flags modify it:

$ reminders add Soon Contribute to open source
$ reminders add Soon Go to the grocery store --due-date "tomorrow 9am"
$ reminders add Soon Something really important --priority high

The due date is parsed from natural language rather than a rigid format, since the example passes "tomorrow 9am" as a quoted string. Priority takes the value high in this example, which is worth checking against what your own macOS version accepts, because the README shows only that one value. After the adds, the list view shows the new entries with the relative timing and the priority in parentheses, for example Go to the grocery store (in 10 hours) and Something really important (priority: high), which is how you confirm the CLI wrote what you intended.

Editing, completing and the undo path

The mutating commands share the list and index form, and the tool prints what it did. Editing replaces the text and can set or clear the due date:

$ reminders edit Soon 0 Some edited text
Updated reminder 'Some edited text'
$ reminders edit Soon 0 --due-date "tomorrow 9am"
$ reminders edit Soon 0 --clear-due-date

Completion marks an item done and uncomplete reverses it, which is why the show command can filter to completed items with --only-completed:

$ reminders show Soon --only-completed
0 Write README
$ reminders uncomplete Soon 0
Uncompleted 'Write README'

That round trip is the most useful thing in the tool, because completing a reminder by mistake is otherwise annoying to undo through the app. One documentation wrinkle: the delete example in the README prints Completed 'Write README' after a delete command, which reads as a copy and paste slip rather than intended behaviour, so check what delete actually reports on your system before scripting around its output.

Three ways to install it

Installation is straightforward because the tool ships as a single executable. The quickest route is Homebrew:

$ brew install keith/formulae/reminders-cli

The second is a release archive, which the README unpacks by hand:

$ tar -zxvf reminders.tar.gz
$ mv reminders /usr/local/bin
$ rm reminders.tar.gz

The third is building from source, which the README says requires a recent Xcode installation:

$ cd reminders-cli
$ make build-release
$ cp .build/apple/Products/Release/reminders /usr/local/bin/reminders

Note that the archive from the releases page is named reminders.tar.gz, while the Makefile builds its own archive named reminders.tar.gz from the executable and a completion script. Since the binary talks to a local database rather than a network service, the only external requirement is a Mac with Reminders available, which is what makes this a macOS-only tool rather than a cross platform one.

A universal binary and generated zsh completions

The Makefile shows how the release artefacts are produced, and two details stand out. The build is a Swift build in release configuration with warnings treated as errors, compiled for both architectures at once:

swift build --configuration release -Xswiftc -warnings-as-errors --arch arm64 --arch x86_64

That single command covers both Apple Silicon and Intel Macs, which removes the usual guesswork about which binary to download. The package target then asks the executable itself for a zsh completion script and bundles it with the binary in the archive:

$(RELEASE_BUILD)/$(EXECUTABLE) --generate-completion-script zsh > _reminders
tar -pvczf $(ARCHIVE) _reminders -C $(RELEASE_BUILD) $(EXECUTABLE)

The target finishes by printing SHA-256 checksums for both the archive and the executable, which is the check you would want before dropping a downloaded binary into a path the shell searches. The repository is a normal Swift package, with Package.swift and Package.resolved at the top level and the code under Sources/ with tests under Tests/.

Swift source, MIT licence, releases from 2024

The project is small and the licence is permissive. The licence field on the repository says MIT, so the code and the idea are both reusable without copyleft obligations. On maintenance, the release history is recent enough to be usable but not fast: version 2.4.0 fixed Sonoma support on 2023-11-09, 2.5.0 added notifications on 2024-02-15, and 2.5.1 fixed a midnight alarm issue for all day reminders on 2024-05-07. The last push to the main branch was on 2026-10-02, so work has continued on the branch since those tags without a new release. That gap is the thing to keep in mind before depending on it: there is no new version to upgrade to, so a Homebrew install still gives you the 2.5.1 binary, and the source on main may contain fixes that the published release does not.

Editorial conclusion

Adopt reminders-cli when you want macOS Reminders to be scriptable from a shell, especially for creating items with a due date from a cron job or a script, and install it with brew install keith/formulae/reminders-cli to get the maintained binary. Do not adopt it if you need reminders shared between machines or platforms, since the tool reaches into a local store that exists only on macOS, and do not script against its output blindly, because the README's delete example prints a completion message that looks like a documentation slip. Verify first that the installed version is 2.5.1 rather than a build from main, that the index you pass to complete or edit still refers to the item you mean, and that the priority value your macOS version accepts is the one the tool sends.

Frequently asked questions

Official sources

1. Issues
2. keith/reminders-cli on GitHub
3. License: MIT
4. README
5. Releases