task_update
Update mutable fields of an OmniFocus task, including name, dates, flags, and tags, using full replacement or diff-based tag changes. Supports dry-run preview and optimistic concurrency.
Instructions
Partially update mutable fields on an OmniFocus task. Only supplied fields are changed; omit a field to leave it unchanged. Do not use to complete or delete a task; prefer task_complete or task_delete instead. Two tag-update modes: (1) supply tagIds to replace the full tag set; (2) supply addTags and/or removeTags to apply a diff without reading first. Supplying tagIds together with addTags/removeTags is a ValidationError. setFlagged is a convenience alias for flagged. Safety controls: set dry_run=true to preview the patched task without mutating; pass expectedModifiedAt (from a recent task_get) to reject the call if the task changed since you read it; pass idempotency_key to coalesce retries so the same update is only performed once. Returns the updated task. Side effects: writes to OmniFocus, sets meta.syncPending = true. Call sync_trigger when you need changes to appear on other devices. Example: task_update({ id: "abc123", flagged: true }) Example: task_update({ id: "abc123", dueDate: "2026-05-01T00:00:00Z", addTags: ["tag456"] })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Persistent task ID. Get from task_list or search_query. | |
| name | No | New task name. Must be non-empty if supplied. | |
| note | No | Plain-text note. Pass null to clear. HTML round-trip available in M3. | |
| tagIds | No | Full-replacement tag list. Replaces all existing tags. Mutually exclusive with addTags/removeTags. | |
| addTags | No | Tags to add. No-op for tags the task already has. Mutually exclusive with tagIds. | |
| dry_run | No | When true, validates input, computes the patched task (pre-fetch merged with the supplied fields), and returns a preview envelope with meta.dryRun = true; no adapter call is made and no mutation occurs. | |
| dueDate | No | ISO-8601 due date with UTC offset. Pass null to clear. | |
| flagged | No | Flag or unflag the task. Alias: setFlagged. | |
| deferDate | No | ISO-8601 defer date with UTC offset. Pass null to clear. | |
| removeTags | No | Tags to remove. No-op for tags the task doesn't have. Mutually exclusive with tagIds. | |
| sequential | No | Whether subtasks must be completed in order. | |
| setFlagged | No | Convenience alias for flagged. Use when your intent is specifically to set or clear the flag without touching other fields. | |
| dueDateFloating | No | When true, the due time is floating (follows the user across time zones). | |
| idempotency_key | No | Idempotency key for retry-safe updates. Identical subsequent calls within the TTL window replay the original envelope with meta.idempotentReplay = true instead of re-applying the patch. | |
| estimatedMinutes | No | Estimated duration in minutes. Pass null to clear. | |
| deferDateFloating | No | When true, the defer time is floating (follows the user across time zones). | |
| expectedModifiedAt | No | Optimistic-concurrency guard: ISO-8601 timestamp from a recent task_get. If the task's current modifiedAt differs, the call fails with OF_CONFLICT and no update is performed. Omit to skip the check. | |
| completedByChildren | No | Whether the task completes when all children are complete. |