Things 3 Task Manager

All commands output JSON arrays. Parse the JSON and present results as clean markdown tables or lists.

Writing Tasks -- scripts/things-create.sh

# Create a task
things-create.sh task "Buy groceries"
things-create.sh task "Review PR" --notes "Check the auth changes" --due "2026-04-01" --tags "Work" --project "Sprint 12" --list "Today"

# Create a project
things-create.sh project "Q2 Planning" --notes "Quarterly goals" --area "Work"

# Complete a task
things-create.sh complete "Buy groceries"

# Move a task to a scheduling list (Today, Someday, Anytime, Tomorrow)
things-create.sh move "Review PR" --list "Today"

# Delete a task
things-create.sh delete "Old task"

All write commands return JSON. Always capture the return value into a variable and inspect it. Every call to things-create.sh must follow this pattern:

RESULT=$(things-create.sh move "Task" --list "Today")
if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
    echo "Error: $(echo "$RESULT" | jq -r '.error')"
else
    echo "Success: $(echo "$RESULT" | jq -r '.name')"
fi

Return value formats:

• Creation success: {"name": "...", "id": "...", "status": "open", ...}
• Complete success: {"completed": "Task Name"}
• Error (ambiguous match): {"error": "Multiple tasks match. Found: Task A, Task B, "} -- parse and display all matching names to the user

Workflow Guidelines

1. Show before modifying: Always call things-query.sh to read the relevant list(s) before any write operations. Display the current state as markdown before making changes.

2. Capture and check every return value: Never discard output from things-create.sh. Always assign it to a variable and check for the error key. When an ambiguity error lists multiple matching task names, display every name to the user.

3. Verify mutations with a follow-up query: After writes, always call things-query.sh to confirm changes:

   • After creating tasks in a project -> things-query.sh project "Name"
   • After completing tasks -> things-query.sh logbook
   • After moving tasks -> query the destination list

4. Build reports from query output, not from creation args: Any report or markdown file showing task data must be written by piping things-query.sh JSON through jq. Do not use shell variables from earlier in the script (like $TASK_NAME or $DUE_DATE) to write the report. The correct pattern is:

   • TASKS=$(things-query.sh project "Name")
   • echo "$TASKS" | jq -r '.[] | "- \(.name) (due: \(.deadline // "none"))"' >> report.md

   This ensures the report reflects verified state from Things 3, not just what was requested.

Raw AppleScript

For operations not covered by the helper scripts (bulk operations, checklist items, relative deadline assignment), compose AppleScript directly using osascript -e. Follow these rules:

• Output: Always use _private_experimental_ json -- never manually build JSON from properties
• Dates: Always use (current date) + N * days -- never date "YYYY-MM-DD" (locale-dependent, wrong results)
• Variables: Use output not result (reserved keyword)
• Empty lists: Guard with count checks before accessing items

See references/applescript-api.md for the full API reference.