@petah/file-organizer

AI-powered CLI tool for organizing files and folders. Uses LLMs via OpenRouter to analyze files and recommend actions like move, delete, archive, or rename.

Installation

npm install
npm link

Configuration

Set your OpenRouter API key:

export OPENROUTER_API_KEY=your_key_here

Optionally set a default model (otherwise uses google/gemini-2.0-flash-001):

export OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

Commands

analyze

Analyze a single file or folder and get an AI recommendation.

file-organizer analyze -f <filename> -d <directory>

Options:

• -f, --file - File or folder name to analyze (required)
• -d, --dir - Base directory (default: current directory)
• -x, --execute - Execute the recommended action (default: dry-run)
• -p, --prompt - Additional instructions for the AI
• -m, --model - OpenRouter model to use (default: google/gemini-2.0-flash-001)
• --debug - Show the full LLM prompt

all

Process all items in a directory.

file-organizer all -d <directory>

Options:

• -d, --dir - Directory to organize (default: current directory)
• --auto - Auto-execute recommendations without prompting
• -l, --limit - Limit processing to N items
• -c, --concurrency - Number of parallel AI requests (default: 5)
• -p, --prompt - Additional instructions for the AI
• -m, --model - OpenRouter model to use (default: google/gemini-2.0-flash-001)
• --debug - Show the full LLM prompt

Interactive mode prompts: [y]es / [n]o / [r]etry / [q]uit

media-rename

Rename media files and folders with messy names (e.g., scene release names).

file-organizer media-rename -d <directory>

Transforms names like:

• The.Matrix.1999.1080p.BluRay.x264-SPARKS → The Matrix (1999)
• Breaking.Bad.S01E01.720p.WEB-DL.AAC → Breaking Bad - S01E01

Options:

• -d, --dir - Directory containing media files/folders
• --auto - Auto-execute renames without prompting
• -l, --limit - Limit processing to N items
• -n, --dry-run - Show what would be renamed without making changes
• -m, --model - OpenRouter model to use (default: google/gemini-2.0-flash-001)
• --debug - Show the full LLM prompt

Interactive mode prompts: [y]es / [n]o / [e]dit / [r]etry / [q]uit

AI Actions

The AI can recommend one of five actions:

| Action | Description | |--------|-------------| | MOVE | Move to a subfolder (existing or new) | | DELETE | Move to _Trash folder | | LEAVE | Keep in current location | | ARCHIVE | Compress the item | | RENAME | Rename folder (folders only) |

Each recommendation includes a confidence level (HIGH/MEDIUM/LOW) and reasoning.

Examples

# Analyze a single file (dry-run)
file-organizer analyze -f "report.pdf" -d ~/Downloads

# Analyze and execute
file-organizer analyze -f "old-backup.zip" -d ~/Downloads -x

# Process all files interactively
file-organizer all -d ~/Downloads

# Auto-organize with custom instructions
file-organizer all -d ~/Downloads --auto -p "Be aggressive about deleting old screenshots"

# Preview media renames
file-organizer media-rename -d ~/Movies --dry-run

# Auto-rename media files
file-organizer media-rename -d ~/Movies --auto

License

MIT