# Rename File

Action

`action.rename_file`

Rename a file in place — change its name while leaving it in the same folder. The source path comes from the upstream payload (typically `{{filePath}}` from a File Changed or Photo Added trigger), and you supply just the new name. The name supports `{{var}}` interpolation, so you can stamp files with dates, counters, or values from earlier nodes (e.g. `{{date}}-{{fileName}}`).

For anything more involved than a single template, add Operations — an ordered stack of transforms (insert text, add a date, slugify, find & replace, regex, and more) applied to the name from top to bottom. A simple template-only rename needs none of it: with no operations, the node behaves exactly as it always has.

Under the hood this is the same operation as Move File pointed at the source's own directory — it exists as its own node because renaming is common enough to deserve a one-field answer.

Collisions are safe by default

If a file with the new name already exists, Rename File auto-numbers the result (`report-1.pdf`) instead of clobbering it. Enabling Overwrite replaces the existing file — which is not recoverable from Trash — so workflows configured that way prompt for confirmation on every arm.

## Ports

Direction | Name | Data Type | Description
--- | --- | --- | ---
Input | Input | Any | Payload with source file path
Output | Output | Any | Payload with the rename result

## Configuration

Field | Type | Default | Description
--- | --- | --- | ---
newName | Text | — | Edited as step 0 (Base name) of the pipeline in the inspector. The new file name (kept in the same folder). Supports `{{var}}` (e.g., `{{date}}-{{fileName}}`). Path separators are stripped — this is a name, not a path. When operations are configured, this may be left empty to start from the file's original name.
operations | Operation stack | empty | Ordered list of rename operations applied after the Base Name template. See Operations below. An empty stack means template-only renaming — identical to the node's original behavior.
overwrite | Boolean | `false` | Replace an existing file with the same name. When off (default), collisions are auto-numbered.

## Operations

Operations are an ordered stack of transforms applied to the file name, top to bottom, after the Base Name template renders. The pipeline works like this:

1. Seed. The name starts as the rendered Base Name template. If the template is empty (or renders empty), the file's original name is used instead — so a stack like "slugify everything that lands in Downloads" needs no template at all.
2. Apply each operation in order. Expand a step to edit it, reorder it with the up/down chevrons, or remove it; order matters (slugify-then-insert is different from insert-then-slugify).
3. Re-attach the extension. The extension is split off once before the stack runs and re-attached at the end. Every operation except Extension Case transforms the base name only — a Truncate or Slugify can never eat the `.pdf`.

The usual safety pass (path separators stripped, name sanitized) still runs last, after the stack.

Operation | Options | What it does
--- | --- | ---
Insert Text | Text; Start / End / At Index | Inserts text into the name. The text supports `{{var}}` interpolation — including dotted paths like `{{exif.dateTakenCompact}}` from Image Metadata. An out-of-range index clamps to the start or end.
Add Date | Source: Today / File Created / File Modified; Format: `yyyy-MM-dd`, `yyyyMMdd`, Timestamp (`yyyy-MM-dd_HH-mm-ss`), or Custom; Start / End; Separator | Joins a date stamp to the name with a separator (`-` by default). Created/Modified read the file's own dates and fall back to now when unavailable.
Parent Folder | Start / End; Separator | Joins the name of the file's containing folder with a separator (`-` by default, e.g. `Downloads-report.pdf`).
Change Case | UPPERCASE / lowercase / Capitalize | Changes the case of the base name (the extension is untouched — use Extension Case for that).
Slugify | kebab-case / snake_case | Makes the name URL/script-friendly: folds accents (Déjà → deja), lowercases, and collapses spaces and punctuation into single separators.
Extension Case | lowercase / UPPERCASE | Changes the case of the file extension only (`.JPG` → `.jpg`).
Truncate | Delete N characters; from Start / End | Removes characters from the base name. Deleting more than exists empties the base name — but if only the extension would remain (a dot-prefixed name Finder hides), the run fails instead of hiding the file.
Find & Replace | Find; Replace; Match Case (on by default) | Replaces every literal occurrence. Both fields support `{{var}}`; an empty Find is a no-op.
Regex Replace | Pattern; Template | Replaces regex matches; the template supports capture groups (`$1`) and `{{var}}`. The pattern is deliberately never interpolated, so payload values can't inject regex syntax. An invalid pattern fails the run with the operation's position in the stack.

Pipeline view. The inspector renders the stack as a vertical pipeline: an editable sample name at the top is the input, every step shows the name as it exists after that step, and the green Result card at the bottom shows the final name — all recomputed as you type, before the workflow ever fires. `{{tokens}}` that haven't resolved yet stay visible verbatim instead of vanishing.

Backward compatible. Existing workflows are unaffected: a node with no operations behaves exactly as before, and the `newName` template works unchanged — the stack is purely additive.

## Output Variables

Variable | Type | Description
--- | --- | ---
renamed | Boolean | `true` on a successful rename; `false` for a no-op (source already gone, or name unchanged)
sourcePath | String | Original file path
destPath | String | New file path after rename
fileName | String | New name of the file
fileSize | Number | File size in bytes

## Safety

The source path is resolved through the standard safety checks before the file is touched, and the new name is collapsed to a bare filename — any `/` or `..` in it is discarded — so a rename can never relocate a file out of its own directory. Sources that resolve to protected locations (`~/Library/`, `~/.ssh/`, system roots) are refused.

To move a file to a different folder (not just rename it), use Move File.

## Example

Date-stamp every screenshot as it appears: