mdsmith rename

Retitle a heading or rename a link-reference label and rewrite every dependent edit; the kind is auto-detected or forced with --as, and a path-shaped request is steered to mdsmith move.

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.

rename changes a symbol inside a file — a heading slug or a link-reference label. To relocate a file, use mdsmith move .

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

<file> is workspace-relative. Absolute paths and parent-traversal entries (../foo.md) are rejected with exit code 2.

# What it rewrites

When <old> names a heading (its current visible text), mdsmith rewrites the heading line. It also rewrites every workspace [text](file.md#slug) anchor link that resolved to it. The matching [label]: file.md#slug ref-defs update the same way. Same-file (#slug) references are included, and a shifted duplicate-name disambiguator updates too.

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

# Choosing heading vs label

The kind is auto-detected from <old>: a heading whose visible text is <old>, or a label normalizing to <old>. Pass --as heading or --as label to force it. When both match, the command exits 2 and asks for --as.

A path-shaped <old> or <new> — one with a slash or a .md / .markdown suffix — that matches no symbol exits 2 and points you at mdsmith move. Renaming a file is a move.

# Safety

The rename refuses to corrupt the workspace. It fails when the new heading slug collides with another heading, when the label collides with another definition, or 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. --dry-run prints the edits and changes nothing.

# Flags

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

# Output

The rewritten files, one per line.

text (default):

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

json:

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

Rows are sorted by path. Keys are stable. The move and dryRun fields appear only for mdsmith move and a dry run.

# Examples

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

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

Force a link-reference label rename:

mdsmith rename docs/guide.md --as label oldlabel newlabel

JSON summary for a release script:

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

# Exit codes

# See also

• mdsmith move — relocate a file and rewrite every reference to it.
• 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).