A native command-line interface for managing Apple Reminders on macOS. Create, inspect, update, and complete reminders — including location-based ones — from Terminal, scripts, or an LLM agent.

The CLI executable is bundled inside the macOS app. The App Store sandbox prevents the app from editing shell files directly, so the setup command prints a user-local symlink command for you to copy into Terminal. The default user-local install does not require sudo.

1. For the standard App Store location, run the bundled CLI command below.
2. If Cinch is installed elsewhere, replace /Applications/Cinch.app with its actual app path.
3. Copy and run the command printed by install-cli. It creates ~/.local/bin/cinch.

"/Applications/Cinch.app/Contents/MacOS/Cinch" install-cli

If Terminal reports cinch: command not found, add ~/.local/bin to PATH. For zsh, add this line to ~/.zshrc:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Open a new Terminal window and verify the installation:

cinch version
cinch doctor --json

doctor is read-only and checks app-bundle resolution, the active parsing locale, execution mode, Reminders authorization, and IPC daemon connectivity without requesting permission.

Third-Party Terminals & IDEs (VS Code, Cursor, AI Agents): The CLI communicates with Cinch via a local App Group UNIX domain socket IPC bridge. Commands run seamlessly through the background app using its Reminders permissions without requiring terminal TCC entitlements.

Use --dry-run to inspect the parsed reminder before creating or updating it. Review the title, due date, priority, list, and repeat rule, then remove --dry-run to commit.

cinch add "Submit report tomorrow at 5pm !!! #Work repeats weekly" --locale en-US --dry-run --json

cinch add --text "Buy milk tomorrow" --locale en-US --dry-run --json

Run cinch schema for machine-readable command definitions, supported locales, natural-language examples, and the error contract.

Priority and list routing

• ! means low, !! medium, and !!! or more high priority.
• Unknown labels such as !high are stripped from the title and do not set priority. Use --priority high for an explicit value.
• Use #Work to route to a matching single-token list. For names with spaces or exact list IDs, use --list.
• Explicit flags such as --title, --due, --repeat, --priority, and --list override matching parsed values.

Tags, contacts, and flags

• Tags: Type #tag or #"Multi-word tag" (e.g. #Work, #"Project Alpha") to assign category tags. If a single-word #Name matches an existing list, it routes to that list; otherwise it is indexed as a tag.
• Contacts: Type @name or @"Full Name" (e.g. @Sarah, @"John Appleseed") to link contact mentions to the reminder.
• Flags: Include !flag in your natural language text or pass the --flag option to mark the reminder with a high-visibility flag.

Dates, times, and language

• Natural-language parsing defaults to the language saved in Cinch. Use --locale on add, or on update to parse --due.
• Supported locale tags: en, cs, de, es, fr, it, ja, ko, pl, pt-BR, sk, and zh-Hans.
• Relative dates, weekdays, clock times, and period phrases are supported. For example, mañana por la tarde resolves to tomorrow at 2pm and is removed from the title.

Repeat phrase examples

• en: daily, every day; weekly, every Monday, repeats weekly; monthly; yearly.
• cs: denně, každý týden, každé pondělí, opakovat týdně; měsíčně; ročně.
• de: täglich, jede Woche, jeden Monat, jedes Jahr. es: cada día, cada semana, cada mes, cada año.
• fr: chaque jour, chaque semaine, chaque mois, chaque année. it: ogni giorno, ogni settimana, ogni mese, ogni anno.
• ja: 毎日, 毎週, 毎月, 毎年. ko: 매일, 매주, 매월, 매년.
• pl: codziennie, co tydzień, co miesiąc, co rok. pt-BR: cada dia, cada semana, cada mês, cada ano.
• sk: každý deň, každý týždeň, každý mesiac, každý rok. zh-Hans: 每天, 每周, 每月, 每年.

Every command, alias, and option in one place — the same details cinch help <command> prints in Terminal. Run cinch schema for machine-readable definitions.

Create and edit

Read and filter

Complete, reopen, and delete

Diagnostics and setup

Global options

• --json — Force JSON output (the default when stdout is piped)
• --plain — Force human-readable output
• --table — Aligned table for cinch list
• --dry-run — Preview add and update without saving

Attach a geofence so a reminder fires when you arrive at or leave a place. Cinch writes the trigger to Apple Reminders, and matching tasks appear in the Nearby section.

Options

• --location <lat,lon|home|work> — Coordinates, or the home/work places saved in Cinch Settings
• --radius <meters> — Geofence radius (default 100)
• --proximity <arriving|leaving> — Fire on arrival (default) or departure
• --on-arrive / --on-leave — Shortcuts for --proximity
• --clear-location — Remove the trigger (update)

cinch add "Buy milk" --location "37.3318,-122.0312" --radius 200 --on-leave
cinch add "Water the plants" --location home --proximity arriving
cinch add "Pick up dry cleaning" --location work --radius 150
cinch update <id> --radius 250
cinch update <id> --clear-location
cinch list --has-location

Notes: on add, --radius and --proximity require --location. On update they retune the existing trigger without repeating --location, and omitting --proximity keeps the current direction.

• When stdout is piped, JSON is the default. --json forces JSON; --plain forces human-readable lines; --table selects a list table.
• Timed due dates serialize as ISO-8601 timestamps; all-day dates serialize as YYYY-MM-DD.
• Reminder objects include isFlagged (boolean), tags (array of strings), and contacts (array of strings).
• Success uses { success: true, data: ..., error: null }. Failure uses { success: false, data: null, error: { code, message } }.

{"success":false,"data":null,"error":{"code":"not_found","message":"Reminder was not found."}}

Exit codes: 0 success; 1 general/operation error; 2 invalid argument or task; 3 Reminders permission denied; 4 requested reminder not found.

Error codes: invalid_task, missing_id, missing_shell, invalid_shell, unknown_command, permission_denied, not_found, fetch_error, save_error, update_error, completion_error, delete_error, and install_error.

Generate zsh, bash, or fish completions and install them in your user configuration:

mkdir -p ~/.zsh/completions && cinch completions zsh > ~/.zsh/completions/_cinch
mkdir -p ~/.local/share/bash-completion/completions && cinch completions bash > ~/.local/share/bash-completion/completions/cinch
mkdir -p ~/.config/fish/completions && cinch completions fish > ~/.config/fish/completions/cinch.fish

For zsh, add fpath=(~/.zsh/completions $fpath) before compinit in ~/.zshrc. Bash needs bash-completion to load its user completion directory; Fish loads its completion directory automatically.

Run cinch doctor for read-only PATH, locale, bundle, and Reminders-permission diagnostics. It never requests permission.

See Support for other help.