CLI Reference

Control Reminders, Calendar, Mail, Music, and every other supported app right from your terminal: scriptable, with structured JSON output you can pipe into other tools. The CLI talks to the Orchard app running on your Mac to do the actual work. Installing it is optional; Skill and MCP integrations both work against the app’s bundled binary without it.

Install the CLI

Open the Orchard menu bar panel and go to More Options.
Click Install CLI Tool. macOS prompts for your administrator password, then creates /usr/local/bin/orchard as a symlink to the CLI binary bundled inside Orchard.app.
Open a new terminal window and run orchard --version to confirm it resolves.

Orchard's More Options page with Install CLI Tool, MCP Config, and Check for Updates

To install manually, symlink it yourself; this requires sudo because /usr/local/bin is owned by root:

sudo ln -sf "/Applications/Orchard.app/Contents/MacOS/orchard-cli" /usr/local/bin/orchard

Updates are automatic

Orchard updates itself in place, and the symlink always points at the same path inside the app bundle, so you never need to reinstall the CLI after an update.

To remove it, click Uninstall CLI Tool in More Options (also requires an administrator password), or run the manual equivalent:

sudo rm -f /usr/local/bin/orchard

Commands at a glance

orchard has 12 subcommands, one per domain. Each maps to an app integration page with the full tool list and example usage:

Command	Docs page
`orchard calendar`	Calendar
`orchard reminder`	Reminders
`orchard clock`	Clock
`orchard mail`	Mail
`orchard contacts`	Contacts
`orchard notes`	Notes
`orchard music`	Apple Music
`orchard weather`	Weather
`orchard messages`	Messages
`orchard location`	Maps
`orchard shortcuts`	Shortcuts
`orchard mcp`	Connect via MCP

Maps is orchard location, not orchard maps

Every other command name matches its app page, but the Maps integration is exposed as orchard location, the command that starts a route, geocode, or nearby-places lookup.

Global options

Every subcommand accepts:

--json: emit structured JSON instead of plain text (see below).
--help / -h: show usage for that specific command.
orchard --version: print the installed CLI version.

Negative coordinates need the equals form

For any numeric flag that can take a negative value (latitude/longitude and similar coordinates — --lat, --lon, or the --lat1/--lng1/--lat2/--lng2 pair used by orchard location route --straight-line), pass it as --flag=value rather than --flag value. A space-separated negative number, like --lon -122.4194, is parsed as a new flag and fails with a usage error (exit code 64); quoting the value doesn’t help. Use --lon=-122.4194 instead.

JSON output structure

With --json, each command prints a single JSON object with up to four keys:

orchard clock time --json

{"output":"Current time in Asia/Shanghai...","success":true}

success: true/false, mirrors the exit code.
output: the tool’s result. If the underlying text is (or ends with) a JSON object or array, it’s parsed into real JSON here; otherwise it’s the raw string.
message (optional): a human-readable prefix that appeared before the JSON payload, when the tool returns both.
rawOutput (optional): the tool’s unparsed original text, present whenever output was parsed out of it.

A tool that returns a human-readable prefix plus structured data populates all four fields:

{"message":"Found 1 event calendars:","output":{"calendars":[{"id":"abc","title":"Work"}],"count":1},"rawOutput":"Found 1 event calendars:\n{\"calendars\":[{\"id\":\"abc\",\"title\":\"Work\"}],\"count\":1}","success":true}

For scripting, pipe structured commands through jq .output and use message for a status line where you want one.

Terminal output of orchard clock time --json showing the output/message/rawOutput structure

Exit codes

Code	Meaning
`0`	Success
`1`	The tool ran but returned an error (permission denied, Pro gate, not found, etc.)
`64`	Usage error: missing or invalid arguments

Getting help

--help works attached directly to the command, or via the orchard help <path> form:

orchard mail read --help
orchard help mail read

Both drill into the exact subcommand and print the same usage text, no matter how deep it’s nested.

Terminal output of orchard --help listing all subcommands

Permissions from the CLI

The CLI itself never holds any macOS permission; Orchard.app does, and every command routes through it. The first time a command touches a new capability (Reminders, Calendar, Contacts, Location, and so on), macOS shows its standard permission prompt in the GUI app, not the terminal. Over SSH or another non-interactive session, grant permissions in advance through System Settings > Privacy & Security, since there’s no window to click “Allow” in. See the Permissions Guide for the full list of what each integration needs.

orchard mcp is the one exception worth calling out: it doesn’t print JSON like the other commands. It runs Orchard as a local MCP server for as long as the parent process keeps it open; see Connect via MCP for how to configure it.