Local File Processor

Process local files with batch rename, format conversion, organization by date/type/metadata, duplicate detection, and metadata read/write/removal.

Process local files with common operations: batch rename, format conversion, organization, duplicate detection, and metadata management.

Installation

brew install exiftool imagemagick ffmpeg
chmod +x ~/.openclaw/workspace/skills/local-file-processor/local-file-processor

Global Safety Flags

These flags work for all commands:

• --dry-run — Preview changes, no files modified/deleted
• --overwrite — Allow replacing existing target files (default is no overwrite)
• --force — Skip confirmation prompts for destructive actions
• --verbose — Verbose output

Commands

rename

local-file-processor rename <pattern> <replacement> [--dir <path>] [--recursive]

Examples:

local-file-processor rename "IMG_" "Photo_" --dir ~/Pictures --dry-run
local-file-processor rename "old" "new" --dir ~/Files
local-file-processor rename "*.jpg" "vacation_{seq}.jpg" --dir ~/Photos

Special replacement tokens:

• {seq} sequence number (001, 002, ...)
• {date} current date (YYYY-MM-DD)
• {time} current time (HH-MM-SS)

---

convert

local-file-processor convert <format> --input <path-or-glob> [--output <dir>] [--quality <1-100>]

Examples:

local-file-processor convert jpg --input "~/Photos/*.png" --dry-run
local-file-processor convert mp3 --input "~/Audio/*.wav" --output ~/converted
local-file-processor convert mp4 --input ./clip.mov --overwrite

Supported formats:

• Images: jpg, jpeg, png, gif, webp, tiff, bmp
• Audio: mp3, m4a, wav, flac, aac, ogg
• Video: mp4, mov, avi, mkv, webm

---

organize

local-file-processor organize <date|type|metadata> [--dir <path>] [--key <metadataTag>]

Examples:

local-file-processor organize date --dir ~/Downloads --dry-run
local-file-processor organize type --dir ~/Documents
local-file-processor organize metadata --dir ~/Photos --key Model

Notes:

• metadata strategy requires --key.
• Metadata-derived folder names are sanitized to prevent traversal/unsafe paths.

---

duplicates

local-file-processor duplicates [--dir <path>] [--recursive] [--action list|delete|move] [--dest <dir>]

Examples:

local-file-processor duplicates --dir ~/Downloads
local-file-processor duplicates --dir ~/Files --action delete --dry-run
local-file-processor duplicates --dir ~/Files --action delete --force
local-file-processor duplicates --dir ~/Photos --action move --dest ~/Duplicates

Notes:

• delete asks for confirmation unless --force is used.
• move requires --dest.

---

metadata

local-file-processor metadata <file-or-glob> [--get <key> | --set <k=v>... | --remove <key>... | --all]

Examples:

local-file-processor metadata photo.jpg --get DateTimeOriginal
local-file-processor metadata "~/Photos/*.jpg" --set "Artist=Jane Doe" --dry-run
local-file-processor metadata photo.jpg --remove Copyright --force

Notes:

• Metadata keys are validated (safe charset only).
• Write/delete metadata operations require confirmation unless --force.

Safety Model

• No overwrite by default for move/convert operations.
• Use --overwrite to explicitly replace existing files.
• Destructive operations require confirmation unless --force.
• --dry-run works for all write/delete operations.
• File scanning uses null-delimited handling for safer filenames.

Troubleshooting

Missing exiftool

brew install exiftool

Missing convert (ImageMagick)

brew install imagemagick

Missing ffmpeg

brew install ffmpeg