Update Task

Update a task's status, priority, description, dates, dependencies, block_id, checklist items, or heading placement in one call. Any combination of these can change together — every field passed is written in a single edit.

Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", status: "done" }) — complete a task; on a Kanban board, auto-moves to the done lane Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", heading: "Done" }) — move a task to a different heading (lands at the top of the lane by default) Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", heading: "Done", position: "bottom" }) — move to the bottom of the lane Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", description: "Updated task name", due: "2026-10-01" }) — change description and set due date Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", due: null }) — clear a date field Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", status: "in_progress", add_subtasks: ["Design", "Implement", "Test"] }) — start working and add checklist stages Example: vault_update_task({ path: "TASKS.md", line: 42, assign_block_id: "my-task" }) — add a block_id to a task that lacks one Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", task_id: "abc123" }) — set a Tasks plugin 🆔 identifier

When to use: Any change to an existing task — completing, starting, re-prioritizing, editing text, setting or clearing dates, adding checklist items, assigning block_ids, or moving between headings. Use vault_list_tasks first to get identification fields (path + block_id or line). For creating a new task, use vault_create_task instead.

Parameters:

• path (required): vault-relative path to the note (must end in ".md").

• Exactly one of block_id or line is required to identify the task.

• At least one change is required. Every field passed is applied in the same single write:

  • status: "todo" | "in_progress" | "done" | "cancelled". Manages checkbox and done/cancelled dates. On a Kanban board, "done" moves the card to the done lane together with its checklist sub-items (their checkboxes are left as they are); a sub-task marked done stays under its parent.

  • priority: "highest" | "high" | "medium" | "low" | "lowest" sets the signifier; null removes it.

  • description: replaces the task text. Metadata fields and block_id are preserved.

  • due / scheduled / start / created: YYYY-MM-DD sets the date; null clears it.

  • task_id: string sets the Tasks plugin 🆔; null clears it.

  • depends_on: non-empty string array sets the Tasks plugin ⛔; null clears it.

  • add_subtasks: non-empty string array — appends one indented [ ] checklist item per entry under the task; existing checklist items are kept. For full sub-tasks with their own metadata, use vault_create_task with parent_block_id.

  • assign_block_id: adds or replaces the ^block-id on the task line. Letters, digits, and hyphens only; must be unique within the note.

  • heading: target heading to move the task to. On Kanban boards this is a lane move; works on any note with headings. Not valid on sub-tasks.

  • position: "top" or "bottom" — where within the target heading the task lands after a heading move or auto-done-lane move. Defaults to "top" (first position in the lane). Ignored when no heading move occurs.

  • Clearing is always explicit null — omitting a field leaves it untouched.

• format: "emoji" or "dataview" — overrides the auto-detected Tasks plugin format.

Errors:

• "note not found" — path does not exist

• "exactly one of blockId or line is required" / "blockId and line are mutually exclusive" — pass exactly one of block_id or line

• "blockId ... not found" — no task line in the note ends with ^block_id

• "no task at line N" — line doesn't contain a task checkbox

• "at least one mutation" — no change params provided

• "cannot move a sub-task to a heading" — explicit heading on a task nested under another task (depth > 0 in vault_list_tasks)

• "heading "X" not found; available: ..." — target heading doesn't exist; the error lists the note's headings

• "multiple done lanes detected" — status "done" on a Kanban board with more than one Complete-marked lane; pass heading to pick the lane

• "no done lane detected" — status "done" on a Kanban board with no Complete marker and no "Done" heading; pass heading explicitly

• "blockId ... already exists" / "blockId ... contains invalid characters" — assign_block_id must be unique in the note and match [a-zA-Z0-9-]+

• "invalid date" — a date param fails calendar validation

• "description cannot be empty" / "dependsOn cannot be empty" / "addSubtasks cannot be empty" / "addSubtasks cannot contain an empty item" — whitespace-only text or an empty array (use null to clear depends_on)

• "description must be a single line" / "addSubtasks items must be a single line" — a task is one file line; a line break in the text would split its metadata onto a line the parser never reads

• "taskId ... contains invalid characters" / "dependsOn entry ... contains invalid characters" — task_id and every depends_on entry must match [a-zA-Z0-9_-]+ (the Tasks plugin's id grammar)

• "concurrent write in progress" — another write to this note is in flight; retry

Returns: JSON { path, line, description, block_id, heading, subtasks, changes } — line is the final 1-based position; description is the current text; block_id and heading reflect the task after the update (block_id is omitted when the task has none, heading when the task sits above the first heading); subtasks lists each checklist item added by add_subtasks as { line, description } (omitted when none were added) — checklist items carry no block_id, so line is the handle for a follow-up update; changes lists every field applied as "field: before → after", with "(none)" for an absent value (for subtasks the two sides are checklist-item counts).