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
1---2name: osascript-apps3description: osascript-apps4---56# osascript-apps78App scripting with confirmed-working patterns for Mail, Calendar, Finder, Notes, Reminders, and Spotlight.9All scripts are Python with AppleScript/JXA embedded as strings.1011## App Capabilities1213| App | API | What's accessible |14|-----|-----|-------------------|15| Mail | AppleScript dictionary | Inbox, search, attachments, accounts, all message properties |16| Calendar | AppleScript (surface) | Title, dates, location, status |17| Calendar | EventKit ObjC (full depth) | + Attendees, organizer, recurrence, alarms |18| Finder | AppleScript dictionary | Disk volumes, file metadata, desktop contents |19| Spotlight | `mdfind` via shell | Full-text search, metadata queries across indexed files |20| Notes | AppleScript dictionary | Note titles, body, creation/modification dates |21| Reminders | AppleScript dictionary | Title, completed state, due date, list |22| Shortcuts | AppleScript (minimal) | Name, ID, action count only — content is opaque |2324## Key Limitations2526- **Shortcuts two-way return**: `run shortcut` returns `missing value` unless shortcut has `accepts input: true` AND ends with "Stop and Output" action.27- **EventKit vs AppleScript**: Use EventKit ObjC for attendees, recurrence, alarms — AppleScript doesn't expose these.28- **mdfind empty results**: Returns empty for directories with `unknown indexing state`. Check with `mdutil -s /path`.29- **Mail TCC**: Mail has its own TCC category — not `kTCCServiceAddressBook`. First use may prompt.3031## Scripts3233Read recent Mail inbox messages with full properties:34```bash35uv run scripts/mail-read.py36uv run scripts/mail-read.py 2037```3839Search Mail inbox by subject or sender keyword:40```bash41uv run scripts/mail-search.py "invoice"42uv run scripts/mail-search.py "from:boss@example.com"43```4445Today's (or next N days') calendar events via EventKit ObjC — includes attendees:46```bash47uv run scripts/calendar-today.py48uv run scripts/calendar-today.py 749```5051Search files by name, content, kind, or date via `mdfind`:52```bash53uv run scripts/spotlight-search.py "budget 2024"54uv run scripts/spotlight-search.py "kind:pdf date:today"55```5657Disk volumes with capacity/free space, or metadata for a specific path:58```bash59uv run scripts/finder-info.py60uv run scripts/finder-info.py ~/Documents/report.pdf61```6263Read recent Apple Notes titles and dates — `--filter` by title keyword:64```bash65uv run scripts/notes-read.py66uv run scripts/notes-read.py 20 "meeting"67```6869Read incomplete (or all) reminders from default list or a named list:70```bash71uv run scripts/reminders-read.py72uv run scripts/reminders-read.py --all73uv run scripts/reminders-read.py --list "Groceries"74```7576## Reference7778- [reference/16-mail-scripting.md](reference/16-mail-scripting.md) — Mail inbox, search, attachments, accounts, full message properties79- [reference/17-calendar-eventkit.md](reference/17-calendar-eventkit.md) — AppleScript vs EventKit comparison, attendees, recurring rules80- [reference/10-spotlight.md](reference/10-spotlight.md) — mdfind CLI, MDQuery ObjC, all metadata attributes81- [reference/12-app-dictionaries.md](reference/12-app-dictionaries.md) — Runtime introspection via `get properties`, Finder, Shortcuts limits82- [reference/13-error-handling.md](reference/13-error-handling.md) — safeExecute wrapper, common error codes (-1719, -1728, -1708)83- [reference/14-sandboxing.md](reference/14-sandboxing.md) — Allowed apps, blocked verbs, dry-run pattern, audit logging
damionrashford