Replace Span
vault_replace_spanReplace a block of whole lines in an Obsidian note using short start/end anchors, avoiding error-prone full-text reproduction for table rows, callouts, or list runs.
Instructions
Replace a contiguous block of whole lines in a note's body with new content, identified by short anchor substrings instead of the block's full text. Each anchor locates a full line — the entire line is selected, not just the matching substring. Same anchor semantics as vault_delete_span. Case-sensitive matching. Properties are preserved; YAML formatting may be normalized to block style on first edit. Operates on the body only.
Example: vault_replace_span({ path: "Tracker.md", start_anchor: "| 2024-03-02 | Acme", content: "| 2024-03-02 | Acme Corp | Updated |" }) — replaces the one table row whose line contains that fragment. Example: vault_replace_span({ path: "Notes/Plan.md", start_anchor: "> [!warning] Stale", end_anchor: "remove after launch", content: "> [!info] Current\n> Updated for v2." }) — replaces the callout block with a new one.
When to use: Replacing a block you have already read — a table row, callout, or run of list items — where reproducing it exactly as old_text would be error-prone. Pick a short, unique fragment of the first line for start_anchor and, for a multi-line block, the last line for end_anchor. Prefer vault_replace_in_note for small in-place text changes (typos, renaming). Prefer vault_delete_span when removing without replacement.
Parameters:
start_anchor + end_anchor define a line range, not a text range — each anchor locates a full line, and the entire line from start to end is replaced (never cuts mid-line). Omit end_anchor for a single-line replace.
end_anchor is searched at or after the start line, so the span can never run backward. If both match the same line, only that one line is replaced.
content replaces the entire matched span and must be non-empty. A trailing newline adds a blank line after the new block.
first_match applies to both anchors independently — when an anchor matches multiple lines, takes the first instead of erroring.
Blank-line runs left by the replacement are collapsed to a single blank line.
Errors:
"note not found" — verify path with vault_list_notes
"anchor not found" — fragment not on any line; verify with vault_read_note
"ambiguous start anchor …" / "ambiguous end anchor …" — the anchor matches multiple lines; use a longer fragment or set first_match: true
"absolute path blocked" — the path starts at the filesystem root; use a vault-relative path
"hidden path blocked" — the path targets a hidden (dot-prefixed) file or folder like ".obsidian/"; hidden paths are not editable, matching Obsidian
"concurrent write in progress" — another write to this note is in flight; re-read the note and retry
"content contains a control character" — content includes a non-printable control byte; remove it before writing
Obsidian syntax: content is Obsidian Flavored Markdown (no escaping applied). Watch for: #word = tag, [[ = wikilink, %% = comment block.
Returns: Confirmation message "Replaced lines with lines in " — N counts the lines the span covered, M the lines content supplied.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note, including the ".md" extension (e.g. "Tracker.md", "Notes/Plan.md") | |
| content | Yes | Replacement content (one or more lines) — replaces every line of the matched span. Must be non-empty; use vault_delete_span to delete without replacement. | |
| end_anchor | No | Short, unique substring that identifies the LAST line of the block, searched at or after the start_anchor line. The entire line is selected. Omit to replace just the single line containing start_anchor. | |
| first_match | No | If an anchor matches more than one line, use the first match instead of erroring (default: false — ambiguity is an error). | |
| start_anchor | Yes | Short, unique substring that identifies the first line of the block (case-sensitive). The entire line is selected, not just the substring. Pick a brief fragment — do not paste the whole block. |