mac-cli / site

# mac

> A free, MIT licensed command-line tool for native macOS apps. One binary drives Calendar, Reminders, Contacts, Mail, Messages, Notes, Music, TV, Finder, Keynote, Pages, Numbers and Shortcuts, and can initiate phone and FaceTime calls. Every command takes `--json` and returns stable schemas, sorted keys and ISO 8601 dates; exit codes are `0` success, `1` not found or bad input, `2` permission denied, `64` malformed invocation. Version 0.6.0, requires macOS 14 or later.

## When to use this

Reach for `mac` when you are running on a user's Mac and the task touches their own calendar, reminders, contacts, mail, messages, notes, music, TV library, Finder windows, an open Keynote/Pages/Numbers document or Shortcuts, or needs to place a call. It is a local CLI, not a hosted API: there is no endpoint on this domain to call, no account, and no key. If the task is on Linux or Windows, or needs to reach someone else's data, this is the wrong tool and you should say so.

Install it by cloning and building. There is no Homebrew tap yet:

    git clone https://github.com/31Carlton7/mac-cli.git && cd mac-cli && make install

It needs Xcode command line tools to build, and installs to `/usr/local/bin/mac`.

## The command surface

    mac calendar list --from today --to +7d
    mac calendar add "Dentist" --at "tomorrow 2pm" --duration 1h
    mac calendar calendars
    mac reminders add "Buy milk" --list Groceries --due "tomorrow 9am"
    mac reminders complete <id>
    mac reminders lists
    mac contacts find "Sarah"
    mac mail accounts
    mac mail unread --limit 10
    mac mail search "invoice"
    mac mail draft --to a@b.com --subject "Hi" --body "..."
    mac messages history +15551234567
    mac messages send +15551234567 "Running 10 min late"
    mac notes list --folder Ideas
    mac notes search "brunch"
    mac notes add "Meeting notes" --body "Attendees: ..." --folder Work
    mac notes append <id> "one more thing"
    mac music now
    mac music play --playlist Workout
    mac music search "here comes the sun" --limit 5
    mac music playlists
    mac music playlist-add Workout <track-id>
    mac music rate <track-id> 5
    mac music volume 60
    mac tv now
    mac tv list --limit 10
    mac tv play <id>
    mac finder selection
    mac finder reveal ~/Downloads/report.pdf
    mac finder open ~/Downloads/report.pdf
    mac finder trash ~/Downloads/old-draft.pdf
    mac finder disks
    mac finder eject "Backup Drive"
    mac keynote docs
    mac keynote add-slide Deck --title "Q3" --body "Revenue up"
    mac keynote export Deck --format pdf --out ~/deck.pdf
    mac pages docs
    mac pages set-body Letter --text "Dear team,"
    mac pages export Letter --format docx --out ~/letter.docx
    mac numbers get-cell Q3 --cell B2
    mac numbers set-cell Q3 --cell B2 --value "42"
    mac numbers export Q3 --format csv --out ~/q3.csv
    mac shortcuts list
    mac shortcuts run "Get Weather" --input "London"
    mac call "+1 555 123 4567"
    mac facetime user@example.com --audio
    mac doctor

Dates accept ISO (`2026-08-27 14:00`), naturals (`tomorrow 2pm`, `friday`) and offsets (`+7d`, `+2h`).

## Rules that matter if you are an agent

- Add `--json` to anything you intend to parse. It prints even under `--quiet`, which suppresses only the human-readable output.
- Mutations (`edit`, `delete`, `complete`, `mark-read`, `archive`) take exact IDs only. Get IDs from `list` or `find` first; never construct one.
- `mac messages send` takes an exact handle and does no normalization. Resolve a name with `mac contacts find` before sending.
- Prefer `mac mail draft` over `mac mail send` unless the user explicitly asked to send.
- A successful `mac messages send` is not proof of delivery. Messages accepts sends to handles never registered with iMessage without a synchronous error. Read the thread back with `mac messages history` to confirm.
- Discovery commands differ in shape: `mac calendar calendars` and `mac reminders lists` return objects (`{id,title,kind}`); `mac mail accounts` returns a plain string array, because a Mail account's name is its identifier.
- Exit `64` means you built the invocation wrong (unknown flag, missing option). Exit `1` is reserved for semantic failure: not found, or bad input.
- Errors are one-line and actionable on stderr. On exit `2`, run `mac doctor`; it names the missing grant and the fix.
- `mac call` and `mac facetime` are initiate-only. They open a `tel:`/`facetime:` URL and macOS shows its own confirmation before dialing, so the command returning `0` means the dialog was raised, not that a call happened. There is no answer, hang-up or call-state surface. Use `--dry-run` to print the URL without opening it.
- `mac music rate` takes 0 to 5 stars. `playlist-delete`, `playlist-add` and `playlist-remove` refuse anything that is not a user playlist, so they will not touch a system or library playlist.
- `mac finder` is for GUI state your shell cannot reach: what the user has selected, revealing a path in a window, mounted disks. It deliberately has no ls/cp/mv, because you already have a shell for that.
- Deleting a user's file? Prefer `mac finder trash <path>` over `rm`. It moves the item to the Trash, which the user can recover from. There is deliberately no empty-trash command, so nothing here can permanently destroy a file.
- The iWork commands (`keynote`, `pages`, `numbers`) act on OPEN documents, addressed by name. An extension-less stem works when it is unambiguous, so `Deck` finds `Deck.key`. If the document is not open, open it first.
- iWork edits are text only. There is no styling, no media, no formulas. `pages set-body` replaces the whole body; `pages append-body` adds to it.
- Numbers `--sheet` and `--table` are 1-based, not 0-based. Getting this wrong is the most common first mistake.
- **Exports never overwrite an existing file unless `--force` is passed.** This is the one place these commands write to a path you chose, so an export that would clobber something fails loudly instead. Do not reach for `--force` to make an error go away; pick a different path, or confirm with the user that the existing file is theirs to lose.
- Shortcut names can collide. A duplicate name is rejected with the candidates listed rather than guessed at; pass `--id` to address one exactly.

## What is true about permissions

macOS prompts once per capability. Calendar, Reminders and Contacts run on the native EventKit and Contacts frameworks. Mail, Messages, Notes, Music, TV, Finder, Keynote, Pages, Numbers and Shortcuts go through AppleScript and, for reading message history, a read-only copy of the Messages database, because Apple ships no public API for those. They additionally need Automation consent and, for Messages history, Full Disk Access for the terminal app. `mac doctor` reports fourteen rows: Calendar, Reminders and Contacts access, Automation consent for Mail, Messages, Notes, Music, TV, Shortcuts Events, Finder, Keynote, Pages and Numbers, and Full Disk Access. `mac call` and `mac facetime` need no grant at all, since opening a URL is not a restricted operation. `mac doctor` reports all of it with fix steps. Nothing leaves the machine: there is no telemetry, no network call and no server component.

## Limits you should design around

- Mail reads are windowed. Every read examines only the newest `--scan` messages (default 30, max 500) per account inbox; older mail is invisible. Cost scales with messages touched: roughly 0.15s each on a small account and ~1.5s each on a 50k-message one, so keep `--scan` small on big mailboxes. Search matches subject and sender only, within that same window.
- Without `--account`, `mac mail unread` is a fast sample rather than a global newest-N: accounts are scanned smallest-inbox-first and scanning stops once `--limit` fills. Pass `--account` when you need determinism.
- Recurring events share one ID across occurrences; `edit` and `delete` act on the series master.
- Edit flags replace values and cannot clear to nil. A due date, once set, cannot be removed. Notes, location and org can be blanked with an empty string; names and titles cannot.
- Duplicate calendar or list names resolve to the first match. Contact phone/email labels are flattened to plain values.
- Messages group chats are read-only. Notes: password-protected notes list but read as empty, `delete` moves to Recently Deleted, and checklists and attachments flatten to plain text.

## Which other Apple apps can be driven at all

Taken from the README, so it stays in step with the source. Use it to decide whether a
task is possible before you attempt it. "No public API" means no tool can script that
app directly, including this one: the workaround is to have the user wrap the job in a
Shortcut and then call `mac shortcuts run "Their Shortcut"`.

A survey of remaining first-party apps, for anyone weighing whether to script them directly or via `mac shortcuts run`.

| App | Status | Notes |
| --- | --- | --- |
| Photos | Scriptable, not yet wired up | Has a real AppleScript dictionary; candidate for a future module. |
| QuickTime Player | Scriptable, not yet wired up | Recording/playback are scriptable. |
| Preview | Scriptable, not yet wired up | Limited but real dictionary (open/print/close). |
| TextEdit | Scriptable, not yet wired up | Full document AppleScript support. |
| Keynote / Pages / Numbers | **Shipped in v6** | `mac keynote` / `mac pages` / `mac numbers`; see the command surface above. |
| Podcasts | No public API | Wrap the task in a Shortcut and run it with `mac shortcuts run`. |
| News | No public API | Same workaround. |
| Stocks | No public API | Same workaround. |
| FaceTime / Phone (beyond dialing) | No public API | `mac call`/`mac facetime` cover initiating a call; anything past that needs the Shortcuts workaround. |
| Maps | No public API | Same workaround. |
| Weather | No public API | Same workaround. |
| Books | No public API | Same workaround. |
| Voice Memos | No public API | Same workaround. |
| Freeform | No public API | Same workaround. |
| Journal | No public API | Same workaround. |
| Home | No public API | Same workaround. |
| Passwords | No public API | Same workaround. |

## Status

Version 0.6.0 is the current release and everything above works today. A Homebrew tap is next. Photos, QuickTime Player, Preview and TextEdit are scriptable and are candidates, but are not wired up, so do not tell a user they can drive those with `mac`. Photos, QuickTime Player, Preview and TextEdit are scriptable and are candidates, but are not wired up yet, so do not tell a user they can drive those with `mac`.

Source and issues: https://github.com/31Carlton7/mac-cli
License: MIT