rename

fialr rename <target> [options]

Rename files using a configurable template pattern. Populates template variables from enrichment metadata and file properties. Dry-run by default.

---

Arguments

Argument	Description
target	Directory containing files to rename (required)

Options

Option	Description
--template PATTERN	Naming template (default: {{ date }}-{{ entity | slugify }}-{{ descriptor | slugify }}.{{ ext | lower }})
--execute	Apply renames (default: dry-run only)
-o, --output PATH	Write rename plan to file
--from PATH	Apply renames from a previously generated rename plan file
--skip PATTERN [...]	Glob patterns for files to skip
--dirs	Rename directories instead of files
--prefix	Apply prefix map from schema.yaml (requires --dirs)

---

Template syntax

Templates use a restricted Liquid-like syntax: variables and filters only. No loops, no macros, no arbitrary code.

Variables

Variables are populated from enrichment output and file metadata:

Variable	Source	Example
date	Document subject date (ISO 8601). Format configurable via date_format.	2024-03-15
entity	Primary subject or organization	acme-corp
descriptor	Semantic description (2-5 words)	quarterly-report
version	Version string (present only when multiple versions coexist)	v2
ext	MIME-derived file extension	pdf
tags	List of semantic tags	["invoice", "2024"]
confidence	Enrichment confidence score	0.92
hash	BLAKE3 hash (first 8 characters)	a1b2c3d4
sensitivity	Tier number	2
category	Schema category	financial
original_name	Original filename	scan001.pdf
mime_type	MIME type	application/pdf
user variables	Custom variables from [naming.variables] in fialr.toml	acme

Filters

Filters transform variable values. Chain multiple filters with |:

Filter	Description	Example
slugify	Lowercase, underscore-join, strip special chars	Acme Corp → acme_corp
lower	Lowercase	PDF → pdf
upper	Uppercase	pdf → PDF
truncate: N	Limit to N characters	long-name → long
default: V	Fallback if empty	{{ version | default: "v1" }}
first	First element of a list	["a", "b"] → a
last	Last element of a list	["a", "b"] → b
join: SEP	Join list elements	["a", "b"] → a-b
replace: OLD, NEW	String replacement	foo_bar → foo-bar
strip	Trim whitespace	" text " → "text"
format: FMT	Date or number formatting	2024-03-15 → Mar 2024

---

What it does

Dry-run (default)

Without --execute, rename shows proposed renames without modifying any files. Each line shows the current filename and the proposed new name.

Execution

With --execute, renames are applied. Each rename includes:

1. BLAKE3 hash verification before rename
2. Provenance recording (original name preserved in XATTRs and SQLite)
3. The rename operation
4. Post-rename verification

---

Configuration

The naming pattern, date format, file-type overrides, and user variables are configured in fialr.toml:

[naming]
# Default pattern — all tokens optional
pattern = "{{ date }}-{{ entity | slugify }}-{{ descriptor | slugify }}.{{ ext | lower }}"

# Separators
separator = "-"
word_separator = "_"

# Case
case = "lower"

# Date output format (strftime)
date_format = "%Y-%m-%d"

# Per-directory pattern overrides
[naming.directories]
"receipts" = "{{ date }}-{{ entity | slugify }}-{{ descriptor | slugify }}.{{ ext }}"
"photos/*" = "{{ date }}-{{ descriptor | slugify }}.{{ ext }}"

# File-type pattern overrides
[naming.patterns]
"*.jpg" = "{{ date }}-{{ descriptor | slugify }}.{{ ext | lower }}"
"*.mp3" = "{{ entity | slugify }}-{{ descriptor | slugify }}.{{ ext | lower }}"

# User-defined variables available in all templates
[naming.variables]
project = "acme"
owner = "jane"

The --template flag overrides the config file value. When --template is not provided, the pattern is resolved from config using this priority:

1. Schema category naming_pattern (per-category override in schema.yaml)
2. Directory pattern — [naming.directories] glob match
3. Config [naming.patterns] matching the file extension
4. Config [naming].pattern (default template)
5. Hardcoded fallback

---

Directory renaming

With --dirs, rename normalizes directory names instead of files:

• Applies the configured case and word separator
• Strips special characters
• With --prefix, applies prefix_map from schema.yaml (e.g., work/ → 01_work/)
• Dry-run by default

---

Output

Dry-run:

rename ~/Documents

  RENAME    14 files (dry-run)
────────────────────────────────────────────────────────
  scan001.pdf → 2024-03-15-acme-quarterly_report.pdf
  IMG_4521.jpg → 2024-06-01-paris-eiffel_sunset.jpg
  doc (1).docx → 2024-01-10-smith-employment_contract.docx

---

Examples

# Preview renames (dry-run)
fialr rename ~/Documents

# Apply renames
fialr rename ~/Documents --execute

# Custom template with hash suffix
fialr rename ~/Documents --template "{{ date }}_{{ entity | slugify }}_{{ hash }}.{{ ext | lower }}"

# Minimal template — omit date
fialr rename ~/Documents --template "{{ entity | slugify }}_{{ descriptor | slugify }}.{{ ext }}"

# Photos — date and descriptor only (no entity)
fialr rename ~/Photos --template "{{ date }}_{{ descriptor | slugify }}.{{ ext | lower }}"

# Include a user-defined variable (set in fialr.toml [naming.variables])
fialr rename ~/Documents --template "{{ project }}_{{ date }}_{{ descriptor | slugify }}.{{ ext | lower }}"

# Preview directory renames
fialr rename ~/Documents --dirs

# Apply directory renames
fialr rename ~/Documents --dirs --execute

# Apply prefix map from schema.yaml
fialr rename ~/Documents --dirs --prefix --execute

---

See also

• Naming Convention — the default naming pattern
• enrich — populate metadata used by rename templates
• organize — full pipeline including rename