omnifocus-cli

OmniFocus CLI

Overview

Use the local bundled CLI instead of direct MCP tool-calling for OmniFocus requests. The MCP server exposes 26 consolidated tools; loading all their schemas into chat is expensive. This CLI gives you the same capabilities as deterministic shell commands.

CLI location: bin/omnifocus-enhanced.cjs (relative to this skill directory).

Flag Conventions

These matter — getting them wrong causes confusing errors:

• Booleans need an explicit value: --flagged true (NOT bare --flagged)
• Arrays are comma-separated: --task-status Available,Next
• Empty string means "move to root": --new-parent-folder-name ""
• Complex/nested args: use --raw '<json>' to bypass flag parsing entirely
• Output: default text is best for user replies; add -o json only when post-processing

Reading Tasks

Use get-tasks with --source to select the view. All views support task-tree aware output with [N subtasks] counts. Detailed reads render an assigned tag's full OmniFocus hierarchy, for example 团队 / 守一. Structured results keep the assigned leaf id and name and add path plus ancestorIds; compact reads continue to omit tags.

# Inbox, flagged, forecast
bin/omnifocus-enhanced.cjs get-tasks --source inbox
bin/omnifocus-enhanced.cjs get-tasks --source flagged
bin/omnifocus-enhanced.cjs get-tasks --source forecast --days 7

# By tag
bin/omnifocus-enhanced.cjs get-tasks --source tag --tag-name "work"

# Custom perspectives (OmniFocus Pro) — read the tasks a perspective produces
bin/omnifocus-enhanced.cjs get-tasks --source custom --perspective-name "今日计划"

# Custom perspectives — read and edit the filter rules themselves
bin/omnifocus-enhanced.cjs manage-perspectives --action list
bin/omnifocus-enhanced.cjs manage-perspectives --action get --name "今日计划"
# Always preview a rule change first; --rules takes the document returned by get
bin/omnifocus-enhanced.cjs manage-perspectives --action update --name "今日计划" \
  --rules '{"match":"all","rules":[{"type":"availability","value":"available"}]}' --dry-run true

# Subtask expansion
bin/omnifocus-enhanced.cjs get-tasks --source inbox --show-subtasks true
bin/omnifocus-enhanced.cjs get-tasks --source flagged --show-subtasks true --max-subtask-depth 1
bin/omnifocus-enhanced.cjs get-tasks --source forecast --days 7 --show-subtasks true --max-subtask-depth 2
bin/omnifocus-enhanced.cjs get-tasks --source tag --tag-name "work" --show-subtasks true

# Single task with attachment metadata
bin/omnifocus-enhanced.cjs get-task-by-id --task-id "<id>"
bin/omnifocus-enhanced.cjs get-task-by-id --task-id "<id>" --show-subtasks true

# Completed today
bin/omnifocus-enhanced.cjs filter-tasks --completed-today true --task-status Completed --sort-by completedDate