A command-line interface for OmniFocus on macOS.
bun install -g @stephendolan/omnifocus-cliRequires Bun and macOS with OmniFocus installed.
of inbox count # Check inbox
of task list --flagged # Flagged tasks
of task create "Buy groceries" # Quick capture
of task update "Buy groceries" --complete # Mark doneof task list # List active tasks
of task list --flagged # Flagged tasks only
of task list --project "Work" # Filter by project
of task list --tag "urgent" # Filter by tag
of task list --completed # Include completed
of task create "Name" [options]
--project <name> # Assign to project
--tag <tags...> # Add tags
--due <YYYY-MM-DD> # Set due date
--defer <YYYY-MM-DD> # Set defer date
--planned <YYYY-MM-DD> # Set planned date
--flagged # Flag the task
--estimate <minutes> # Time estimate
--note <text> # Add note
of task update <name|id> [options]
--complete / --incomplete # Mark completed/incomplete
--drop / --undrop # Mark dropped/restore to active
--flag / --unflag # Toggle flag
--name <new-name> # Rename
--project/--tag/--due/--defer/--planned # Same as create
of task view <name|id> # View details
of task delete <name|id> # Delete taskof project list # List active projects
of project list --folder "Work" # Filter by folder
of project list --status "on hold" # Filter by status
of project list --dropped # Include dropped
of project create "Name" [options]
--folder <name> # Assign to folder
--tag <tags...> # Add tags
--sequential # Sequential project
--note <text> # Add note
of project view <name|id> # View details
of project delete <name|id> # Delete projectof tag list # All tags with counts
of tag list --unused-days 30 # Stale tags
of tag list --sort usage # Most used first
of tag list --sort activity # Most recent first
of tag list --active-only # Only count incomplete tasks
of tag stats # Usage statistics
of tag create "Name" # Create tag
of tag create "Child" --parent "Parent" # Nested tag
of tag view <name|path|id> # View details
of tag update <name> --name "New" # Rename
of tag update <name> --inactive # Deactivate
of tag delete <name> # Delete tagof inbox list # List remaining inbox tasks and subtasks
of inbox count # Count remaining inbox tasks
of inbox add "Task name" # Add task to inboxof perspective list # List all perspectives
of perspective view "Forecast" # View tasks in perspectiveof folder list # List all folders
of folder list --dropped # Include dropped
of folder view "Work" # View folder details
of folder create "Work" # Create or reuse a top-level folderfolder create matches exact top-level names, including dropped folders. It
returns the folder fields plus alreadyExisted: false for a new folder and
true when reusing one. Nested folders with the same name do not match. The
create_folder MCP tool accepts { "name": "Work" } with the same behavior and
is available in full mode only.
of task stats # Task statistics
of project stats # Project statistics
of tag stats # Tag statisticsof search "query" # Search tasksof doctor # Check consent without prompting or sending an Apple eventThe doctor reports status: "granted", osStatus: 0, execPath, target, and
promptRequested: false when allowed. Consent failures return a JSON error
with name (automation_consent_required for -1744 or automation_denied for
-1743), statusCode: 403, osStatus, and execPath, and exit with code 1.
Every OmniFocus operation runs the same non-prompting preflight before sending
an Apple event. MCP tools return the same typed JSON with isError: true.
of doctor --request-consent explicitly allows a macOS consent prompt. Use it
only during attended setup in the intended client context. Agent contexts must
never use that flag or probe OmniFocus directly: macOS can attribute child
processes to an unapproved ancestor, and a queued consent dialog can block all
OmniFocus scripting. Route live reads through an approved localhost MCP listener.
The diagnostic execPath identifies the CLI runtime; TCC may attribute the call
to an ancestor instead. See MCP operations.
Run as an MCP server for AI agent integration:
of mcp # stdio, for agents on this Mac
of mcp --http # Streamable HTTP at http://127.0.0.1:3939/mcp
of mcp --http 4000 # Same, on another portThe initialize response advertises an original purple checkmark icon as embedded
128×128 and 64×64 PNG data URIs in serverInfo.icons, for both stdio and HTTP.
Set OMNIFOCUS_MCP_ICON_PNG to a readable PNG path to use your own icon. The image
is loaded at startup and embedded with its actual dimensions; an unreadable file
or invalid PNG header prevents startup. Clients can load the icon without a
separate image request. Display and caching depend on the client; reconnecting
may refresh its icon.
HTTP mode listens on 127.0.0.1 and accepts only localhost and 127.0.0.1 as the Host. To reach it from other devices on your tailnet, allow the Mac's MagicDNS name and publish the port with tailscale serve:
of mcp --http --allow-host <machine>.<tailnet>.ts.net
tailscale serve --bg --https=8443 http://127.0.0.1:3939
claude mcp add --transport http omnifocus https://<machine>.<tailnet>.ts.net:8443/mcpFull mode is the default (27 tools). Use --mode read-only for the 16-tool read-only allowlist; direct calls to excluded tools are rejected, including get_perspective_tasks because it changes the front window.
For an authenticated public reverse proxy, require Cloudflare Access JWT validation at the origin:
of mcp --http 3940 --allow-host omnifocus.example.com --mode full \
--access-team-domain https://example.cloudflareaccess.com \
--access-audience YOUR_ACCESS_AUDIENCEBoth Access options are required together; CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUDIENCE provide the same configuration through environment variables. JWT validation applies on localhost too. The origin verifies the RS256 signature using the team's rotating JWKS, exact issuer, application audience, and expiry. Without Access configuration, anyone who can reach the listener can use its configured capabilities; keep that listener on a trusted tailnet.
See MCP operations for release, health checks, and separate public-listener and tunnel LaunchAgents.
All commands output JSON. Use --compact for single-line output.
of task list | jq 'length' # Count tasks
of task list | jq '.[] | .name' # Task names
of task list --flagged | jq '.[] | {name, due}' # Specific fields{
"id": "kXu3B-LZfFH",
"name": "Task name",
"completed": false,
"flagged": true,
"project": "Project Name",
"tags": ["tag1", "tag2"],
"due": "2024-01-15T00:00:00.000Z",
"defer": null,
"planned": null,
"estimatedMinutes": 30,
"note": "Notes here",
"added": "2024-01-01T10:00:00.000Z",
"modified": "2024-01-10T15:30:00.000Z",
"completionDate": null
}Permission denied: Grant automation permission in System Settings > Privacy & Security > Automation.
Task not found: Use exact name or ID. IDs appear in JSON output.
Date format: Use ISO format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS.
git clone https://github.com/stephendolan/omnifocus-cli.git
cd omnifocus-cli
bun install
bun run dev # Watch mode
bun link # Link globally as `of`MIT