renamr 1.1.0

CLI tool that renames local files using AI-powered metadata extraction

renamr

AI-powered CLI that renames files based on their content.

What it does

Scanned documents, downloads, and exported files often arrive with useless names like scan_001.pdf or IMG_5847.jpg. renamr reads each file — extracting text from PDFs, rendering pages as images for vision models, or encoding photos directly — sends a preview to an LLM, and renames the file to a structured format based on the content it actually finds.

scan_001.pdf          ->  240115_ACME_Invoice.pdf
IMG_5847.jpg          ->  241203_PostOffice_DeliveryNotice.jpg
invoice_download.pdf  ->  250110_Amazon_OrderConfirmation.pdf

Only the filename changes. Files are never modified.

Features

• Content-aware renaming via any LiteLLM-supported provider (OpenAI, OpenRouter, Anthropic, local models)
• PDF text extraction for text-based documents
• Vision model support for scanned PDFs and image files
• iCloud evicted file handling — auto-downloads stubs via brctl before processing (macOS only)
• Multi-inbox support — configure one or more folders in a single config
• Configurable output language — extracted metadata returned in any language
• Dry-run mode to preview renames without touching files
• Undo the last run with a single command
• Configurable output template ({date}_{sender}_{subject}), file extensions, and system prompt
• Optional in-place PDF compression after renaming

Installation

Requires Python 3.12 or newer.

pip install renamr

uv tool install renamr

Quick Start

# One-time global install
uv tool install renamr   # or: pip install renamr

# First-run setup — creates ~/.config/renamr/config.toml
renamr init

# Set your API key
export OPENAI_API_KEY="your-key"

# Preview renames
renamr run --dry-run

# Rename files
renamr run

# Undo last run
renamr undo

Override the inbox without editing config:

renamr run --inbox ~/Documents/inbox --dry-run

Configuration

renamr init creates ~/.config/renamr/config.toml by default. On Linux, XDG_CONFIG_HOME is respected, so the actual path becomes $XDG_CONFIG_HOME/renamr/config.toml when set.

The full set of options:

inbox_paths = ["/path/to/your/folder"]
language = "en"
file_extensions = [".pdf", ".jpg", ".jpeg", ".png", ".txt"]
recursive = false
filename_template = "{date}_{sender}_{subject}"
# rename_prompt = "..."  # override the system prompt sent to the model

[llm]
model = "gpt-4o-mini"
api_base = ""        # leave empty for direct OpenAI; set for OpenRouter or local endpoints
temperature = 0.2
max_retries = 2
timeout = 60

[compress]
enabled = false      # re-render PDFs at lower DPI after renaming
dpi = 150
jpeg_quality = 80

[logging]
level = "INFO"
json_logs = false

inbox_paths accepts one or more folders. renamr run processes all of them in one pass. Use --inbox /some/folder for a one-off override without editing the config.

filename_template supports three placeholders: {date}, {sender}, {subject}. Changing the order does not affect metadata extraction — the model still returns the same fields, and renamr only changes how they are assembled into the final filename.

undo.json is stored next to the config file. With the default setup, that means ~/.config/renamr/undo.json.

Switching providers. Change model and set api_base. For OpenRouter:

[llm]
model = "openrouter/openai/gpt-4o-mini"
api_base = "https://openrouter.ai/api/v1"

Then set OPENROUTER_API_KEY instead of OPENAI_API_KEY. Any provider supported by LiteLLM works without code changes.

Customizing the prompt. The default system prompt extracts sender, subject, and date from documents and handles German and English. To override, uncomment rename_prompt in config.toml and replace it with your own. The full default is in src/renamr/models.py.

Privacy & Security

[!WARNING] renamr sends file content to an external LLM API.

Depending on your configuration, this includes:

• Extracted text from PDF and .txt files
• Rendered page images from scanned PDFs
• Raw image data from .jpg, .png, and other supported image files
• Original filenames and file timestamps

This data is transmitted to your configured LLM provider and may be processed on remote servers. Do not run renamr on sensitive or confidential files unless you have reviewed and accepted your provider's data handling policy.

Run renamr run --dry-run first to confirm which files will be processed.

Additional notes:

• Always use an https:// endpoint for api_base. An http:// URL sends file content unencrypted.
• Keep ~/.config/renamr/undo.json private on shared systems — it contains the file paths from the last run.
• Avoid sharing verbose log output publicly; failed auth responses may include API key fragments.

Maintenance

This tool is maintained for personal use and published as-is. Bug reports welcome via Issues. No guaranteed response time. PRs accepted if they align with the project's scope.

See CONTRIBUTING.md for development setup.

License

MIT