remindctl

remindctl is a macOS CLI tool that interfaces with Apple's public EventKit APIs. This ensures that all changes made via the CLI sync through the standard Reminders and iCloud paths.

Supported Features

• Core Management: Due dates, alarms, recurrence, priorities, notes, completion, and deletion.
• Organization: Support for exact list IDs and location triggers.
• Automation & Output: Emits data in JSON (for automation), TSV (using --plain), and tables (using --format table).
• Agent/Scripting Tools: Includes doctor --for-agent for workflow checks, export for data extraction, and link for deep linking.

Limitations

remindctl stays within public EventKit limits. It does not expose private Reminders.app features such as:

• Tags
• Sections
• Smart lists
• Attachments
• The "Urgent" toggle

Dates and Due Times

Use --due with the following formats:

• today, tomorrow, yesterday
• YYYY-MM-DD or YYYY-MM-DD HH:mm
• ISO 8601 (e.g., 2026-01-03T12:34:56Z or 2026-01-03T12:34:56)
• Legacy formats like MM/dd/yyyy or dd-MM-yyyy are supported.

Alarms

Timed due reminders get an automatic alarm. Use --alarm to set a custom time or --clear-alarm to remove it.

Recurrence (Repeat)

Use --repeat with add or edit. Supported values:

• daily, weekly, biweekly, monthly, yearly
• every N days/weeks/months/years

remindctl add "Meeting" --due "2026-01-03 09:00" --alarm "2026-01-03 08:55"
remindctl add "Take vitamins" --due tomorrow --repeat daily
remindctl edit 4A83 --repeat weekly

Before initiating a formal release, you must synchronize versioning information across the project and run preflight checks.

Required synchronization:

• CHANGELOG.md (finalize the section)
• version.env
• package.json
• Sources/remindctl/Version.swift
• Embedded Info.plist

Preflight commands: Run the following to ensure code quality and release readiness:

make format
make check
make docs-site
make release-harness
make release-check TAG=vX.Y.Z

Note: make macos-artifact can be used to create an optional, credential-free local candidate for testing, which produces dist/remindctl-macos-local.zip. This file is for local testing only and must never be uploaded to an official release.

The list command can be used to view lists or perform mutations like creating, renaming, or deleting them.

Mutation Rules:

• You must choose exactly one of --create, --delete, or --rename.
• Mutation operations accept exactly one list name.
• Create: list <name> --create creates a missing list or reuses a unique matching list. If the name is ambiguous, the command fails.
• Rename: list <name> --rename <new_name>.
• Delete: list <name> --delete --force.

Resolution Logic: List names are resolved by: 1. Exact match (case-insensitive), 2. Normalized match (ignoring emoji and punctuation). If a name is ambiguous, use --list-id to be precise.

remindctl list
remindctl list Work --rename Office
remindctl list Projects --create
remindctl list OldList --delete --force

Use these commands to find specific items, inspect details, or move data out of remindctl.

Search and Inspect:

• search "<query>": Search for text within reminders. Can be scoped to a list with --list <name>.
• info <id>: Show detailed information about a specific reminder.

Export and Handoff:

• export: Export reminders. Use --json for machine-readable data or --export-format csv for spreadsheets.
• link <id>: Generates a link for a reminder.
• open <id|--list <name>>: Opens a reminder or a list view. Use --app to open the specified list directly in the Reminders.app GUI.
• completion zsh: Generates Zsh completion scripts.

remindctl search "invoice" --list Work
remindctl info 4A83 --json
remindctl export --list Work --export-format csv
remindctl open --list Work --app

Once the signing gate is granted, use the managed-keychain wrapper to run the official packager. This process handles Developer ID signing (OpenClaw Foundation) and Apple notarization.

Command:

/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release \
  codesign-run -- scripts/package-macos-release.sh vX.Y.Z

Requirements:

• You must supply the runtime signing locator and NOTARYTOOL_PROFILE through the approved handoff (do not persist these values).
• The packager validates the identity, notary profile, and the Accepted notary response.
• Upon success, it writes three official assets to dist/release-vX.Y.Z/: remindctl-macos.zip, checksums.txt, and release-inventory.json.

Official releases require a verified, signed, and annotated Git tag.

1. Ensure the main branch is the live remote default SHA.
2. Create a verified signed annotated tag (e.g., vX.Y.Z) at the exact commit intended for release.
3. Push the tag and verify that the remote tag object and the peeled commit match your local environment.

Use scripts/check-release-source.sh to perform these checks and generate the deterministic source proof required for subsequent release gates.

Use remindctl with time-based or status-based commands to view your reminders. You can filter these views by a specific list using --list <name> or --list-id <id-prefix>, or view multiple lists simultaneously by passing multiple names to the list command.

Time-based views:

• today, tomorrow, week, overdue, upcoming, open, completed, all.
• week includes incomplete reminders due within the current calendar week (including the start, excluding the opening midnight of the next week).
• You can also pass a specific date like 2026-01-03 to view reminders for that day.

# View specific timeframes
remindctl today
remindctl overdue

# Filter a view to one list
remindctl show overdue --list Work
remindctl show overdue --list-id 7A12

# Show multiple lists together
remindctl list Work Errands

After notarization, create a draft release on GitHub. This helper revalidates your local signed/notarized assets before dispatching the release workflow.

Command:

scripts/create-release-draft.sh vX.Y.Z

This command creates a draft containing the exact title, changelog body, source commit target, and the three official assets.