enquire-mcp API reference - v4.0.0-rc.7
    Preparing search index...

    Function renameNote

    • Rollback-aware note rename with cross-vault backlink rewrite.

      Closes the longstanding "renaming breaks all backlinks" pain point. Walks every note, finds wikilinks / embeds whose findBestMatch resolves to the source file, rewrites only those literals (preserving |alias, #section, ^block, and the user's path-qualification convention), then commits the file through Vault's classified exclusive/overwrite path. dry_run returns the same plan without touching disk.

      Self-references inside the renamed file are also rewritten in the same pass — the file ships with no broken self-links. For a case-only spelling of the same canonical directory entry, the shared source/destination entry stays in that source rewrite plan; only a distinct destination entry is excluded. A distinct hardlink destination fails closed because byte-level rollback cannot restore link topology. v3.7.13 M1 — write order is recoverable: (1) rewrite source content at OLD path → (2) perform the classified move before any backlink writes → (3) rewrite backlink-bearing files after the destination exists. Guaranteed precommit validation failures restore the rewritten source snapshot; later partial backlink failures retain the resumable ordering. This is not a transactional guarantee against out-of-process check/use or ABA races. Pre-v3.7.13 the order was (backlinks → source → rename), which left backlinks rewritten to the NEW name pointing at a phantom destination when the rename step failed. WRITE TOOL — only registered when --enable-write is passed.

      Parameters

      • vault: Vault

        The vault. Must allow writes.

      • args: { dry_run?: boolean; from: string; overwrite?: boolean; to: string }

        from and to are vault-relative paths (with or without .md). dry_run defaults to false — when true, returns the plan without writing. overwrite defaults to false — when true, allows replacing an existing destination.

      • options: WriteOperationOptions = {}

        Optional MCP cancellation signal. Under a stable out-of-process filesystem identity, cancellation during the apply phase restores rewritten backlinks, source path/content, and a snapshotted overwritten destination before rejecting. A two-step exclusive move that publishes its destination but cannot remove its source is reported as an incomplete rollback rather than a successful cancellation. The planning receipt narrows but cannot eliminate an out-of-process check/use or ABA race.

      Returns Promise<RenameNoteResult>

      A RenameNoteResult with per-file rewrites and totals.

      If source doesn't exist, a distinct destination exists and overwrite is false, source equals destination, destination is a distinct hardlink, destination identity is unproven or changed, or destination is privacy-excluded.

      If either path resolves outside the vault.

      // Preview first
      const plan = await renameNote(vault, {
        from: "Inbox/draft-1.md",
        to: "Posts/Hybrid Retrieval.md",
        dry_run: true
      });
      console.log(`Would update ${plan.files_updated.length} files`);

      // Apply
      await renameNote(vault, { from: "Inbox/draft-1.md", to: "Posts/Hybrid Retrieval.md" });

    Settings
    Member Visibility