Replace in Note
vault_replace_in_noteReplace exact text in a note's body without affecting properties. Replace first or all occurrences, or delete text by using empty replacement.
Instructions
Find and replace text in a markdown note's body. Matches exact text (case-sensitive). Properties are preserved; YAML formatting may be normalized to block style on first edit. Operates on the body only — properties must be edited via vault_update_properties or vault_write_note's properties parameter.
Example: vault_replace_in_note({ path: "Projects/plan.md", old_text: "TODO: write summary", new_text: "Summary complete." })
When to use: Targeted text changes within a single location — fixing typos, updating values, renaming terms, or removing a short line (new_text=""). Replaces text in place; does not move content across sections. To delete a large multi-line block, prefer vault_delete_span (short anchors instead of full old_text). To relocate content between headings, vault_patch_note to add at the target first, then remove from source (new_text="") — add-before-delete, so a failure duplicates the block instead of losing it.
Parameters:
old_text is matched in the body only — frontmatter properties are never searched. Include enough surrounding context to ensure uniqueness when the target text appears in multiple places.
old_text + new_text together determine the operation: a non-empty new_text is an edit; an empty new_text ("") is a deletion. No regex — exact text only.
replace_all_occurrences (default false) replaces only the first match — a safety default when old_text appears in multiple places. Set true for deliberate bulk renames or term replacements.
Errors:
"note not found" — path does not exist; check vault_list_notes for valid paths
"text not found" — old_text does not appear in the note body; verify exact text with vault_read_note
"old_text cannot be empty" — old_text must be at least one character
"concurrent write in progress" — another write to this note is in flight; re-read the note and retry
Obsidian syntax: new_text is Obsidian Flavored Markdown (no escaping applied). Watch for: #word = tag, [[ = wikilink, %% = comment block in replacement text.
Returns: Confirmation message with replacement count (number of occurrences replaced).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note, including the ".md" extension (e.g. "Projects/plan.md") | |
| new_text | Yes | Replacement text. Empty string ("") deletes the matched text. | |
| old_text | Yes | Exact text to find (case-sensitive). Matches in the body only — text inside frontmatter properties is not searched. | |
| replace_all_occurrences | No | Replace all occurrences (default: false — replaces first occurrence only) |