name: osascript-apps
description: Script macOS apps via AppleScript/JXA: Mail, Calendar (EventKit attendees), Notes, Reminders, Finder (disk/file info), and Spotlight/mdfind (full-text and metadata search across the file system).
osascript-apps
App scripting with confirmed-working patterns for Mail, Calendar, Finder, Notes, Reminders, and Spotlight.
All scripts are Python with AppleScript/JXA embedded as strings.
App Capabilities
| App | API | What's accessible |
|---|
| Mail | AppleScript dictionary | Inbox, search, attachments, accounts, all message properties |
| Calendar | AppleScript (surface) | Title, dates, location, status |
| Calendar | EventKit ObjC (full depth) | + Attendees, organizer, recurrence, alarms |
| Finder | AppleScript dictionary | Disk volumes, file metadata, desktop contents |
| Spotlight | mdfind via shell | Full-text search, metadata queries across indexed files |
| Notes | AppleScript dictionary | Note titles, body, creation/modification dates |
| Reminders | AppleScript dictionary | Title, completed state, due date, list |
| Shortcuts | AppleScript (minimal) | Name, ID, action count only — content is opaque |
Key Limitations
- Shortcuts two-way return:
run shortcut returns missing value unless shortcut has accepts input: true AND ends with "Stop and Output" action.
- EventKit vs AppleScript: Use EventKit ObjC for attendees, recurrence, alarms — AppleScript doesn't expose these.
- mdfind empty results: Returns empty for directories with
unknown indexing state. Check with mdutil -s /path.
- Mail TCC: Mail has its own TCC category — not
kTCCServiceAddressBook. First use may prompt.
Scripts
Read recent Mail inbox messages with full properties:
uv run scripts/mail-read.py
uv run scripts/mail-read.py 20
Search Mail inbox by subject or sender keyword:
uv run scripts/mail-search.py "invoice"
uv run scripts/mail-search.py "from:boss@example.com"
Today's (or next N days') calendar events via EventKit ObjC — includes attendees:
uv run scripts/calendar-today.py
uv run scripts/calendar-today.py 7
Search files by name, content, kind, or date via mdfind:
uv run scripts/spotlight-search.py "budget 2024"
uv run scripts/spotlight-search.py "kind:pdf date:today"
Disk volumes with capacity/free space, or metadata for a specific path:
uv run scripts/finder-info.py
uv run scripts/finder-info.py ~/Documents/report.pdf
Read recent Apple Notes titles and dates — --filter by title keyword:
uv run scripts/notes-read.py
uv run scripts/notes-read.py 20 "meeting"
Read incomplete (or all) reminders from default list or a named list:
uv run scripts/reminders-read.py
uv run scripts/reminders-read.py --all
uv run scripts/reminders-read.py --list "Groceries"
Reference
- reference/16-mail-scripting.md — Mail inbox, search, attachments, accounts, full message properties
- reference/17-calendar-eventkit.md — AppleScript vs EventKit comparison, attendees, recurring rules
- reference/10-spotlight.md — mdfind CLI, MDQuery ObjC, all metadata attributes
- reference/12-app-dictionaries.md — Runtime introspection via
get properties, Finder, Shortcuts limits
- reference/13-error-handling.md — safeExecute wrapper, common error codes (-1719, -1728, -1708)
- reference/14-sandboxing.md — Allowed apps, blocked verbs, dry-run pattern, audit logging
