npm package: @petah/file-organizer
Description: AI-powered CLI tool for organizing files and folders using LLMs via OpenRouter
Author: Petah
Latest version: 1.1.0

# @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

```bash
npm install
npm link
```

## Configuration

Set your OpenRouter API key:

```bash
export OPENROUTER_API_KEY=your_key_here
```

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

```bash
export OPENROUTER_MODEL=anthropic/claude-3.5-sonnet
```

## Commands

### analyze

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

```bash
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.

```bash
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).

```bash
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

```bash
# 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