docs/user/tools/cli/rename.md
Rename notes, tags, sections, or block anchors — with automatic link rewriting.
foam rename <subcommand> [options]
All subcommands update every wikilink that references the renamed item across the whole workspace.
Rename a note file and rewrite all wikilinks pointing to it.
foam rename note (<identifier> | --path <path>) <new-name>
| Option | Description |
|---|---|
--target-path <path> | Move the file to a different directory |
--path <path> | Target by exact file path |
Example:
foam rename note old-name new-name
# Renamed: notes/old-name.md → notes/new-name.md (id: new-name, 4 links updated)
Move to a different directory at the same time:
foam rename note my-note my-note --target-path archive/
Rename a tag and all its hierarchical children across the workspace.
foam rename tag <old-tag> <new-tag>
| Option | Description |
|---|---|
--force | Skip confirmation if the rename would merge two existing tags |
Example:
foam rename tag project/active project/in-progress
# Renamed: #project/active → #project/in-progress (3 notes updated)
Rename a heading section in a note and rewrite all [[note#Section]] links pointing to it.
foam rename section (<identifier> | --path <path>) <old-label> <new-label>
| Option | Description |
|---|---|
--path <path> | Target by exact file path |
Example:
foam rename section my-note "Background" "Context"
# Renamed section "Background" → "Context" in notes/my-note.md (2 links updated)
Rename a block anchor in a note and rewrite all [[note#^id]] links pointing to it.
foam rename block (<identifier> | --path <path>) <old-id> <new-id>
| Option | Description |
|---|---|
--path <path> | Target by exact file path |
Example:
foam rename block my-note key-insight better-insight
# Renamed block ^key-insight → ^better-insight in notes/my-note.md (1 link updated)
| Option | Description |
|---|---|
--workspace <dir> | Workspace root (default: FOAM_WORKSPACE env var, then current directory) |
--format <fmt> | Output format: text (default) or json |
See also [wikilinks] for how wikilinks work, and [block-anchors] for block anchor syntax.