apple-tools

name

apple-tools

description

Read and write the local Mac's Apple apps via the `apple-tools` CLI. Use whenever you need to act on the user's own macOS data — e.g. make or check reminders, read/search/draft email, view or add calendar events, look up contacts, send an iMessage/SMS, read/write/append notes, find or fetch files, search/export photos, list/export/transcribe voice memos, read or write the clipboard, take a screenshot, or open a URL/mailto/tel link. Covers Calendar, Reminders, Notes, Contacts, Mail, Messages (iMessage/SMS), Photos, Voice Memos, Files, clipboard, screenshots, and opening URIs. Prefer this over ad-hoc osascript/AppleScript for these tasks — osascript can return incomplete results (e.g. a partial Reminders list); this does NOT apply when osascript itself is the thing being developed.

apple-tools

A single CLI, apple-tools, exposes the Mac's Apple integrations. Each tool is a subcommand; most dispatch on an action. Run it via Bash.

Invocation

apple-tools <tool> <action> [--flag value ...]
apple-tools <tool> --json '{"action":"...", ...}'   # raw escape hatch
apple-tools <tool> --help                            # parameters for a tool
apple-tools list                                     # all tools
apple-tools permissions                              # preflight / trigger TCC prompts

• Flags map to the tool's parameters; --calendar-name and --calendar_name are equivalent. Array params (e.g. --attachments) accept repeats or commas.
• Output is JSON on stdout (pretty-printed). Exit code is non-zero on error, with a message on stderr.
• ISO 8601 for dates/times (e.g. 2026-06-15T09:00:00Z).
• Every invocation posts a macOS notification summarizing what ran (e.g. "reminders lists → 14 result(s)"), so the user sees each action. Pass --quiet (or set APPLE_TOOLS_QUIET=1) to suppress it — e.g. for a burst of read calls where one banner per call would be noisy.

Permissions (first run)

Tools use macOS TCC permissions (Calendar, Contacts, Photos, Full Disk Access for Mail/Messages, Screen Recording for screenshots, Speech Recognition for voicememos transcribe). The first access to each triggers a system dialog. Run apple-tools permissions once up front to surface them all, then grant in System Settings → Privacy & Security. If a tool returns an access/permission error, tell the user which permission to grant.

Files

File-producing actions (photos fetch, screenshot, documents fetch, clipboard read on an image, email/imessage fetch_attachment) write the file to a local output dir and return its absolute path in the JSON. Read that path directly with the Read tool. Override the location with --output-dir <dir> or $APPLE_TOOLS_OUTPUT_DIR (default: a private per-user temp dir).

Writes and sends — confirm first

These actions change state or are visible to others. Confirm with the user in chat before running them: imessage send, email draft (creates a draft), calendar create, reminders create/complete, notes create/append, clipboard write, open_uri. (--confirm additionally pops a native Allow/Deny dialog; off by default.)

Tools

• calendar — calendars (list calendars), list (events in a range), search (by keyword), create (add event; does not send invites).
• reminders — lists, search, get, create, create-list (new list, optional --account; rejects duplicate names), complete.
• notes — folders, search, read, create, append. Content is Markdown (headings, bold/italic/strike/mono, lists round-trip). --folder takes a name or a /-separated path as reported by folders; on create, missing path segments are created nested.
• contacts — search (name/email/phone/group), get (by ID).
• email — inbox, search, read, fetch_attachment, draft (does NOT send; supports attachments by absolute path).
• imessage — recent, read, search, send (iMessage/SMS; supports attachments), fetch_attachment.
• photos — search, fetch (export a photo locally → path).
• voicememos — list (recent recordings; last 30 days by default, --all for the full history), search (by title/folder/date), export (copy a recording's .m4a locally → path), transcribe (on-device transcript of a recording; writes a .txt to the output dir and returns its path plus a short preview; cached per recording, so repeat calls are instant; --timestamps writes a .json segment sidecar, --inline returns the full text in the response; macOS 26+). Read-only.
• documents — search (Spotlight), list, info, fetch (copy a file locally → path). Scoped to ~/Documents.
• clipboard — read, write.
• screenshot — capture the screen → local PNG path.
• open_uri — open a URL / mailto: / tel: / app deep link.
• echo — connectivity check.

Run apple-tools <tool> --help for the exact parameters of any tool.

Examples

apple-tools calendar list --start 2026-06-15T00:00:00Z --end 2026-06-16T00:00:00Z
apple-tools reminders create --list "Today" --title "Call plumber" --due 2026-06-16T17:00:00Z
apple-tools reminders create-list --name "Shannon" --account iCloud
apple-tools contacts search --query "Jane"
apple-tools notes read --title "Trip plan"
apple-tools email search --query "invoice" --limit 10
apple-tools imessage send --to "[phone]" --text "on my way"
apple-tools screenshot --output-dir /tmp/shots

Setup

If apple-tools is not found, build and install it from the project repo: bin/install-skill (builds the release binary and links it onto PATH).