Skip to content

README.md

Latest commit

 

History

History
300 lines (225 loc) · 8.04 KB

README.md

File metadata and controls

300 lines (225 loc) · 8.04 KB
Raw

Apple Reminders CLI

A powerful command-line interface for Apple Reminders built with Swift and EventKit.

Features

  • Complete Reminder Management - Create, update, complete, delete reminders
  • List Management - Filter reminders by list
  • Advanced Search - Filter by priority, dates, tags, URLs, alarms
  • JSON Output - Machine-readable output for automation and scripting
  • Enhanced Features - Tags, notes, URLs, and notifications
  • Statistics - Track productivity metrics and completion rates
  • Priority Management - High/Medium/Low priority levels
  • Date Support - Flexible date parsing (natural language, ISO, relative)
  • Attachments - URLs, notes, alarms, and notifications

Installation

Homebrew (Recommended)

# Add the tap
brew tap AungMyoKyaw/homebrew-tap

# Install the CLI
brew install AungMyoKyaw/homebrew-tap/reminder

Build from Source

cd apple-reminders-cli
./install.sh          # Builds and installs both CLI and man page

By default, this installs to ~/.local/bin (no sudo required). To install system-wide:

./install.sh --system  # Installs to /usr/local/bin (requires sudo)

You can also specify a custom prefix:

./install.sh --prefix /custom/path

Or manually:

cd apple-reminders-cli
xcodebuild -scheme apple-reminders-cli -configuration Release
# Copy binary to /usr/local/bin/reminder
# Copy reminder.1 to /usr/local/share/man/man1/reminder.1

Updating the Man Page

The man page is automatically generated from your ArgumentParser configuration using Swift Package Manager. To regenerate the man page after updating command definitions:

cd apple-reminders-cli
./generate-man.sh        # Generates and updates reminder.1

Or run the Swift Package Manager plugin directly:

swift package plugin generate-manual

Why this approach?

  • ✅ Always in sync - Man page automatically reflects your command definitions
  • ✅ Zero maintenance - No need to manually edit .1 files
  • ✅ Built-in support - Uses ArgumentParser's native documentation plugin
  • ✅ Professional format - Generates mdoc-formatted UNIX man pages
  • ✅ Version controlled - Keep reminder.1 in git for distribution

Documentation

The CLI includes comprehensive documentation accessible in multiple ways:

Man Page

# View the full man page
man reminder

# Search within man page (press '/' then type query)
# Quit with 'q'

The man page covers:

  • All commands with detailed options
  • Tag system and usage
  • Date formats and priority levels
  • Examples and common workflows
  • Permissions and system requirements

CLI Help

# Show main help
reminder --help

# Show command-specific help
reminder create --help
reminder search --help
# Get help for any command
reminder help <command>

This README

Quick start guide, common commands, and feature overview.

Quick Start

# List all reminders
reminder list

# Create a new reminder
reminder create "Buy groceries" --priority high --due-date tomorrow

# Complete multiple reminders
reminder complete "Buy groceries" "Call Mom"

# Delete multiple reminders
reminder delete "Spam" "Old Task"

# Show help
reminder --help

Common Commands

List Reminders

reminder list
reminder list Work
reminder list --priority high --uncompleted-only

Create Reminders

reminder create "Meeting" --due-date today --priority high
reminder create "Project" --due-date "2025-12-31" --notes "Important"
reminder create "Buy groceries #shopping #urgent" --due-date tomorrow
reminder create "Review doc" #work #review

Tags

Tags help organize reminders and make them searchable. Tags are stored in the task title (prefixed with #) for proper Apple Reminders app support.

Creating reminders with inline tags:

# Single tag
reminder create "Buy milk #shopping" --due-date tomorrow

# Multiple tags
reminder create "Fix bug #work #urgent #backend" --due-date today

# Tags with priority and dates
reminder create "Deploy release #production #important" --priority high --due-date tomorrow

Searching by tag:

# Search reminders by tag
reminder search --tag work
reminder search --tag shopping --list-name Work

Tag Format:

  • Tags must start with # followed by alphanumeric characters
  • Multiple tags are space-separated: #tag1 #tag2 #tag3
  • Tags are case-sensitive: #work, #Work, and #WORK are different tags
  • Punctuation after tags is automatically stripped: #urgent, #pending! becomes #urgent #pending
  • Tags are appended to the end of task titles for maximum compatibility with Apple Reminders

Update Reminders

reminder update "task" --new-priority medium
reminder update "task" --new-due-date tomorrow
reminder update "task" --new-due-date remove   # Remove due date

JSON Output

All listing and search commands support JSON output for integration with other tools like jq.

reminder list --json
reminder search "meeting" --json | jq '.[0].title'
reminder show "task" --json

Search & Stats

reminder search "meeting" --priority high
reminder search --completed --completed-after 2026-02-01
reminder search --completed --completed-before 2026-02-09 --json
reminder stats

Reference

Priority Levels

Priority Symbol Values
High !!! 1-4
Medium !! 5
Low ! 6-9
None 0

Date Formats

  • Natural language: today, tomorrow, yesterday
  • Relative: in 3 days, in 2 weeks, in 1 month
  • ISO format: 2025-12-31
  • With time: 2025-12-31 14:30

Symbols

  • ☐ - Uncompleted reminder
  • ☑ - Completed reminder
  • !!! - High priority
  • !! - Medium priority
  • ! - Low priority
  • 🔗 - Has URL attachment
  • 🔔 - Has alarm/notification
  • 📝 - Has notes
  • ⚠️ - Overdue

Permissions

On first run, grant Calendar/Reminders access:

System Settings → Privacy & Security → Calendars

Enable access for your terminal app or the CLI executable.

Troubleshooting

Gatekeeper / "Malware" Error

Since this tool is built from source and not signed with an Apple Developer account, you might see an error: “reminder” is free of malware that may harm your Mac...

To solve this:

  1. Open your terminal.
  2. Run the following command: 
    # If installed via install.sh (default)
xattr -d com.apple.quarantine ~/.local/bin/reminder

# If installed system-wide
sudo xattr -d com.apple.quarantine /usr/local/bin/reminder
  3. Alternatively, right-click the executable in Finder, select Open, and then click Open again in the warning dialog.

Tag Behavior & Compatibility

Tag Storage:

  • Tags are now stored in the task title (after the task name) for full compatibility with Apple Reminders
  • This allows tags to sync across all Apple devices and apps
  • Tags are automatically extracted and cleaned during reminder creation

Backward Compatibility:

  • Tags previously stored in notes are still recognized and searchable
  • Search function works for tags in both title and notes
  • Existing reminders with tags in notes continue to work

Examples:

# Create task with tags - tags are extracted and appended to title
reminder create "Buy groceries #shopping #urgent"
# Result: Title becomes "Buy groceries #shopping #urgent"

# Tags are visible in Apple Reminders and other Apple apps
reminder list
# Output: ☐ Buy groceries #shopping #urgent

# Search works across all tag locations
reminder search --tag shopping
# Finds reminders with #shopping in title or notes

Tips

  • Fuzzy matching: Use partial reminder/list names
  • Priority shortcuts: h, m, l, n or numbers 0-9
  • Date shortcuts: today, tomorrow, in 3 days
  • Command help: Use reminder help <command> for detailed options

Built With

  • Swift - Native macOS development
  • EventKit - Apple's Calendar and Reminders framework
  • ArgumentParser - Command-line argument parsing

Version

3.0.4 - Full feature parity with Reminders app