Apple CLI

A local macOS CLI and MCP server for Apple apps.

Install · Usage · Targets · MCP · Documentation

Overview

Apple apps, from your terminal. apple brings Notes, Reminders, Calendar, Mail, Photos and other Apple app and system targets to one macOS command, with structured JSON output and an optional MCP server for local agents.

• Script everyday workflows. Search Notes, organize Reminders, inspect calendars, query Photos and work with local files.
• Use predictable output. JSON results, stable error codes and bounded reads make commands usable in scripts.
• Connect your agent. The MCP server exposes the same CLI capabilities through stdio or Streamable HTTP.

Alpha preview · macOS arm64. Feature availability depends on the target, OS, account and permissions. See the Release Guide for the tested build environment and installation details.

Quick look

Every command follows one shape:

apple <target> <resource?> <action> [options]

Install

Build from source

Use macOS with an Xcode toolchain providing Swift 6.3 or newer and the Notes private frameworks required by the package. From the repository root:

scripts/bootstrap
xcrun swift build --force-resolved-versions
.build/debug/apple --help

Rerun scripts/bootstrap after changing Xcode or the SDK. The declared macOS 13 deployment floor is a build setting; runtime support requires validation on the intended OS and architecture.

Releases

No release has been published yet. From the first release, two channels install it on macOS arm64.

Homebrew, from the organization tap, which installs both executables and their runtime libraries from the accepted GitHub release and declares the tested macOS requirement:

brew install computer-mcp/tap/apple-cli
apple --version

Release archive, built, tested and published by GitHub Actions on GitHub Releases. In the download directory, replacing VERSION:

shasum -a 256 -c apple-cli-VERSION-macos-arm64.tar.gz.sha256
tar -xzf apple-cli-VERSION-macos-arm64.tar.gz
export PATH="$PWD/apple-cli-VERSION-macos-arm64/bin:$PATH"
apple --version

Keep the complete bin directory together: apple, apple-cli-mcp and any bundled Swift runtime libraries. The Release Guide covers relocation, signatures and compatibility.

Usage

Discover a target and check its readiness:

apple --help
apple notes --help
apple notes doctor --json

Read app data with explicit queries and limits:

apple notes search --query "Plan" --limit 20 --json
apple reminders lists list --json
apple calendar calendars list --json
apple photos media-items search --keyword travel --limit 20 --json

Preview a reminder before creating it. Replace Today with an existing list:

apple reminders create \
  --list Today \
  --title "Follow up" \
  --dry-run \
  --json

An explicit create request can then run with the same list and title:

apple reminders create --list Today --title "Follow up" --json

Structured output

--json returns an envelope with ok and data. Errors use ok: false and a stable error.code. Add --pretty for readable formatting. The Quick look's notification preview works without accessing app data or sending a notification.

Permissions and writes

Start with apple <target> doctor --json when a target cannot access an app or its data. Some workflows need macOS permissions or app automation approval.

Use --dry-run to inspect a proposed mutation. External dispatch, destructive selections and system operations require the specific --allow-* flag named by the command. --json controls output; authorization comes from the requested operation and its gates. See Safety Gates for the full contract.

Targets

Choose a target to open its user guide:

Workflow	Targets
Notes and planning	notes · reminders · calendar · contacts
Communication	mail · messages · facetime
Browsing, media and files	safari · maps · photos · finder
Documents	pages · numbers · keynote
System utilities	print · clipboard · notifications · intelligence · tcc

Coverage varies by target. Pages focuses on metadata and export; Keynote supports native slide reads and PDF export alongside cached previews. Numbers supports reads, exports and single-cell writes. Safari Tab Group mutations and some Notes media workflows return an explicit unsupported result. Read the Capability List for the supported scope of each target.

MCP

apple-cli-mcp connects local MCP clients to the apple CLI. Configure your client with the full path to the executable and stdio as its argument:

Client setting	Value
Command	/path/to/extracted-release/bin/apple-cli-mcp
Arguments	stdio

For Homebrew, get the full command path with echo "$(brew --prefix)/bin/apple-cli-mcp". To start the server directly:

apple-cli-mcp stdio

The adapter finds apple beside its own executable. Keep both programs and the bundled runtime libraries together. For a separate CLI directory, set APPLE_CLI_BIN_DIR to the directory containing apple.

Streamable HTTP is also available on loopback:

apple-cli-mcp serve http --host 127.0.0.1 --port 8765 --path /mcp

The same target permissions and mutation gates apply through MCP. See MCP setup for discovery, remote access and authentication.

The source tree also includes a Reminder Creator skill for modeling reminder content, lists, sections and shopping workflows. See its shopping reference for scenario guidance.

Requirements

• macOS on arm64, the tested runtime; see the Release Guide.
• To build: an Xcode toolchain with Swift 6.3 or newer and the Notes private frameworks the package requires.
• Per target: the macOS permissions or app automation approval its workflows need.

Documentation

Start here	What it covers
User guide	Discovery, output, permissions, MCP and workflow safety
Target guides	User and developer documentation for every target
Release guide	Installation, source builds and runtime requirements
Release reference	Version sources, candidate acceptance, CI publication and evidence
Version rules	Organization version rules and repository acceptance requirements
Architecture	CLI ownership, implementation mechanisms and MCP boundaries
Security	Vulnerability reporting

Contributing

scripts/bootstrap
xcrun swift test --force-resolved-versions
scripts/validate-public-content

The default suite uses fixtures and controlled backends. Real app behavior, accounts and OS compatibility need separate validation; the Release Guide describes the available integration checks. See the contributor guide for repository conventions.

License

Copyright (c) 2026 Xudong Xu. Licensed under the Apache License 2.0. Third-party components retain their own licenses; see Third-Party Notices.