mdsmith rename

Rename a heading or link-reference label and rewrite every dependent edit.

The CLI surface for the same rename engine the LSP server drives, so a script or agent with no editor reaches it too. Every dependent edit across the workspace is rewritten in place.

mdsmith rename [flags] <file> <old> <new>

<file> is workspace-relative. Absolute paths and parent-traversal entries (../foo.md) are rejected with exit code 2. Exactly one of --heading or --link-ref is required.

With --heading, <old> is the heading’s current visible text. mdsmith rewrites the heading line. It also rewrites every workspace [text](file.md#slug) anchor link and every [label]: file.md#slug ref-def whose target resolved to it. Same-file (#slug) references are included. A duplicate-name disambiguator that shifts as a result is updated too.

With --link-ref, <old> is the label. It is matched after the lowercase / whitespace-collapse normalization links already use. The [label]: url definition moves with every [text][label] and shortcut [label] use in the file.

The rename refuses to corrupt the workspace. It fails when the new heading slug collides with another heading. It fails when the label collides with another definition. It fails when the text slugifies to nothing, or carries a newline or a stray bracket. Each failure exits 2 and names the conflict. No partial edit is written.

# Flags

--follow-symlinks and file discovery (the files: and ignore: patterns in .mdsmith.yml) match mdsmith check .

# Output

A summary of the rewritten files, one per line.

text (default):

docs/guide.md: 1 edit(s)
docs/index.md: 2 edit(s)

json:

[
  {
    "file": "docs/guide.md",
    "edits": 1
  }
]

Rows are sorted by path. Keys are stable.

# Examples

Rename a heading and fix every link that pointed at it:

mdsmith rename docs/guide.md --heading "Old Title" "New Title"

Rename a link-reference label:

mdsmith rename docs/guide.md --link-ref oldlabel newlabel

JSON summary for a release script:

mdsmith rename --format json docs/guide.md --heading "Setup" "Install"

# Exit codes

# See also

• mdsmith deps — the dependency edges the rename walks to find dependent anchors.
• mdsmith lsp — the editor surface for the same rename engine (prepare-range, collision data).