apple-cli

Apple apps, from your terminal. apple-cli brings 19 Apple app and system targets to one macOS command, with structured JSON output and an optional MCP server for local agents.

Install · Quick start · Targets · MCP · Documentation

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.

• 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.

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

Install

Homebrew

On macOS arm64, install from the organization tap:

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

The Homebrew tap installs both executables and their runtime libraries from the accepted GitHub release. Its formula declares the tested macOS requirement.

Release archive

Download the macOS arm64 archive and its checksum from GitHub Releases. Release archives are built, tested and published by GitHub Actions.

For 0.1.0-alpha.3, run these commands in the download directory:

shasum -a 256 -c apple-cli-0.1.0-alpha.3-macos-arm64.tar.gz.sha256
tar -xzf apple-cli-0.1.0-alpha.3-macos-arm64.tar.gz
export PATH="$PWD/apple-cli-0.1.0-alpha.3-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.

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.

Quick start

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.

This preview works without accessing app data or sending a notification:

apple notifications preview --title Build --body Done --json --pretty

{
  "data": {
    "externalAction": false,
    "notification": {
      "body": "Done",
      "title": "Build"
    }
  },
  "meta": {
    "target": "notifications"
  },
  "ok": true,
  "warnings": []
}

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 and Keynote focus on metadata and export; 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 installed 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.

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.

Development

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.

Documentation

Start here	What it covers
User guide	Discovery, output, permissions, MCP and workflow safety
Target guides	User and developer documentation for all 19 targets
Release guide	Installation, CI publication and compatibility
Version rules	Version upgrades, prereleases and release evidence
Architecture	CLI ownership, implementation mechanisms and MCP boundaries
Contributing	Repository conventions and validation
Security	Vulnerability reporting

License

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