Update Task
vault_update_taskUpdate an existing Obsidian task's status, priority, dates, recurrence, dependencies, checklist items, heading, or lane position in a single edit, identified by block ID or line.
Instructions
Update a task's status, priority, description, dates, recurrence, completion action, dependencies, block_id, checklist items, heading, or position within a lane, in any combination; every field passed is written in a single edit. A repeated call with add_subtasks adds the items again, and a repeated "done" or "cancelled" moves its date stamp to the retry day, so after a timeout or lost response, re-read the task before retrying.
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", recurrence: "every week" }) — make a task recurring Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", heading: "Done" }) — move a task to a different heading (the checkbox is unchanged) Example: vault_update_task({ path: "TASKS.md", block_id: "my-task", description: "Updated task name", due: "2026-10-01", scheduled: null }) — change the description, set one date, and clear another 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
When to use: Any change to an existing task. 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:
Exactly one of block_id or line is required to identify the task. A Kanban sub-task this server created has no block_id, so re-read its line with vault_list_tasks just before an update by line. After a write, wait a few seconds for the listing to catch up.
At least one change is required. Clearing is always explicit null — omitting a field leaves it untouched.
status side effects: Kanban: "done" moves the card and everything nested under it to the done lane (the lane whose first line is Complete, else the heading "Done", exact case), leaving nested checkboxes as they are; a sub-task stays under its parent. Recurring (🔁), on "done" only: spawns the next occurrence, dates advanced per the rule, directly above the completed task, which keeps its nested lines. When the Tasks plugin's settings put the next recurrence on the line below, the spawn goes on the line directly below the task instead, so the task's nested lines then sit under the spawn. The spawn stays in the source lane with no block_id, 🆔, or ⛔ — follow up with assign_block_id on next_occurrence.line, except on an indented line of a Kanban board. Completing by line is NOT idempotent for recurring tasks (the spawn occupies the old line); prefer block_id. Delete (🏁 delete / [onCompletion:: delete]), on "done": removes the task line and its children instead of moving to done. With 🔁 + 🏁, the next occurrence is still created, and the completed task is removed.
recurrence: a rule ending "when done" bases the next occurrence on the completion day. When set together with status "done", the new rule governs the next occurrence. Setting recurrence to null while completing removes the rule and completes without spawning.
on_completion: passed together with status, the submitted value governs the delete decision — "keep" while completing a "delete" task prevents the deletion.
position: applies to a heading move or an auto-done-lane move; otherwise it reorders the task within its current lane. Ignored when the task is deleted on completion.
Errors: (messages use camelCase names, e.g. assignBlockId for assign_block_id)
"note not found" — path does not exist; check the path with vault_list_notes
"path must end in …" — add the .md extension
"absolute path blocked" / "path traversal blocked" / "hidden path blocked" — pass a vault-relative path with no dot-prefixed part
"exactly one of blockId or line is required" / "blockId and line are mutually exclusive" — the message states the rule
"blockId ... not found" / "blockId ... is inside a fenced code block or comment" — no task line outside a fenced code block or %% %% comment ends with that ^id; check the id with vault_list_tasks, or target by line
"blockId ... matches N task lines" — the message lists the lines; target the intended task by line, then repair: on a regular note, give all but one line a new id with assign_block_id; on a Kanban board, where the plugin copies a sub-task's id onto its card, clear the sub-task's id (assign_block_id: null, by line) and give the card the id its links use, or a new one
"no task at line N" / "line N is inside a fenced code block or comment" — the line holds no task checkbox, or sits inside a fenced code block or %% %% comment; re-read line numbers with vault_list_tasks, or target by block_id
"checkbox "[c]" is a NON_TASK status" / "no checkbox symbol for status ..." — in the Tasks plugin's status settings, the task's checkbox character (c) is typed NON_TASK, or the named status has no symbol and its default character has another type; the user changes that character's type or adds the symbol there, then restarts the server
"at least one mutation" — the message lists the fields that count
"cannot move a sub-task to a heading" / "cannot reposition a sub-task" — a heading or position on a task nested under another task (depth > 0 in vault_list_tasks); sub-tasks move with their parent, so move or reposition the parent instead
"cannot reorder a task that sits above the first heading" — position without a heading on a task before the first section heading; the message names the fix
"cannot reorder within "X" — the heading appears N times" / "cannot place at position P under "X" — the heading appears N times" — the heading name is duplicated in the note: the task's own heading for a reorder in place, the one in heading for a move; for a cross-lane move use "top" or "bottom" (they place under the first match), or rename one section to make it unique
"heading "X" not found; available: ..." — the message lists the note's headings
"multiple done lanes detected" / "no done lane detected" — status "done" on a Kanban board with more than one lane whose first line is Complete, or with none and no "Done" heading; pass heading to pick the lane
"blockId ... already exists" / "blockId ... contains invalid characters" — assign_block_id must be unique in the note and match [a-zA-Z0-9-]+
"assignBlockId is not allowed" / "description ends in a block ID" / "subtask ... ends in a block ID" — a new ^id on an indented line of a Kanban board; leave the line without an id and target it by line, and drop any trailing ^id from the text
"invalid date: …" — the message names the expected format
"description cannot be empty" / "addSubtasks cannot contain an empty item" / "description must be a single line" / "addSubtasks items must be a single line" — pass visible text on a single line
"taskId ... contains invalid characters" / "dependsOn entry ... contains invalid characters" — the message names the allowed characters
"unrecognized recurrence rule ..." — the message gives example rules
"concurrent write in progress" — another write to this note is in flight; retry
"ENAMETOOLONG: …" or another filesystem error — the message says what to do
"properties block …" — the note's properties block can't be read, or a rewrite would lose it; the error says how to repair it
"the note would open with a properties block …" — a note without properties would start with --- lines around text that can't be properties; the error says how to avoid it
Obsidian syntax: When description or add_subtasks text ends in a field the plugin's parser recognizes (an emoji field like "🔁 every week", or a Dataview [key:: value] field), with only other recognized fields after it, that text is read back as metadata. The write still succeeds; reword the text to clear the advisories the result carries. The ✅/❌ dates a status change adds or removes produce no advisories.
Returns: JSON { path, line, description, block_id, heading, subtasks, next_occurrence, changes, advisories, on_completion_applied }.
line is the task's final 1-based line number in the file; after an on_completion delete, the line the task occupied before removal.
description is the current text, and 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 add_subtasks wrote as { line, description } (omitted when none were added); checklist items are written without a block_id, so line is the handle for a follow-up update.
next_occurrence is present only when a completion spawned a recurring task's next occurrence: { line, description, due?, scheduled?, start? } with only the dates the occurrence has.
changes lists every field applied as "field: before → after", with "(none)" for an absent value; an add_subtasks change is listed under "subtasks", a spawn under "next_occurrence", and a 🏁 delete under "on_completion".
advisories (omitted when there are none) lists one sentence for each: a stored line that parses back differently than submitted (see Obsidian syntax above), a duplicate tag removed from the line, or a completed recurring task whose rule yields no next occurrence (unreadable rule text, or a finite rule with no occurrences left).
on_completion_applied is "delete", present only when the effective on_completion was delete (already on the task or set in the same call) and the task was transitioned to done.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>"
},
"name": "vault_update_task"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due | No | Due date (YYYY-MM-DD) to set, or null to clear. | |
| line | No | 1-based line number from vault_list_tasks. Fragile if the file changed since the query. | |
| path | Yes | Vault-relative path to the note containing the task (must end in ".md"). Use the exact letter case. | |
| start | No | Start date (YYYY-MM-DD) to set, or null to clear. | |
| format | No | Field format for metadata this call writes; fields it leaves alone keep theirs. Default: auto-detected from .obsidian/ config, falling back to emoji. | |
| status | No | Target status. "done" adds the ✅ date and "cancelled" the ❌ date, when the Tasks plugin's settings stamp them; moving a task out of either status removes its date. | |
| created | No | Created date (YYYY-MM-DD) to set or clear, for corrections. | |
| heading | No | 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. | |
| task_id | No | Tasks plugin 🆔 identifier to set, or null to clear — letters, digits, hyphens, and underscores; separate from block_id. | |
| block_id | No | Stable task identifier — the ^block-id at the end of the task line, without the ^. Preferred over line. | |
| position | No | Where within the target heading the task lands. "top" or "bottom" for the extremes; an integer (1-based) for an exact position among the lane's top-level cards (sub-tasks move with their parent and are not counted). A position past the card count lands directly below the last card (unlike "bottom", which appends after any non-task text at the end of the section). Defaults to "top" on heading and done-lane moves. | |
| priority | No | Priority signifier to set, or null to remove it. | |
| scheduled | No | Scheduled date (YYYY-MM-DD) to set, or null to clear. | |
| depends_on | No | Tasks plugin ⛔ dependency IDs to set (non-empty), or null to clear. | |
| recurrence | No | Tasks plugin 🔁 rule in natural language (e.g. "every week", "every month on the 15th", "every 2 weeks when done") to set, or null to remove it. | |
| description | No | New task description text; metadata fields and block_id are preserved. | |
| add_subtasks | No | Checklist items to append, one indented todo line each, under the task's existing items. Not appended, and not reported, when the same call removes the task (on_completion delete). For full sub-tasks with metadata, use vault_create_task with parent_block_id. | |
| on_completion | No | Tasks plugin 🏁 onCompletion action to set, or null to remove it. "keep" leaves the task in place on completion, as having no 🏁 field does. | |
| assign_block_id | No | Add or replace the ^block-id on the task line, or null to remove it. Letters, digits, and hyphens only; must be unique within the note. |