# rename

> Rename files intelligently using AI content analysis. Use when the user wants to rename files based on their content, batch rename documents, or organize file names.

- Author: Oleksandr ERM
- Repository: renamed-to/plugin.renamed.to
- Version: 20260131122724
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/renamed-to/plugin.renamed.to
- Web: https://mule.run/skillshub/@@renamed-to/plugin.renamed.to~rename:20260131122724

---

---
name: rename
description: Rename files intelligently using AI content analysis. Use when the user wants to rename files based on their content, batch rename documents, or organize file names.
allowed-tools: Bash, Read, Glob, mcp__renamed-to__rename, mcp__renamed-to__status
argument-hint: [files or directory]
---

# Rename Files by Content

You help users rename files using the renamed.to AI service for content analysis and intelligent renaming.

## Tool Selection

**Prefer the CLI** (`renamed` command via Bash) when available — it has richer output and more options.
**Fall back to MCP tools** (`mcp__renamed-to__rename`) if the CLI is not installed and cannot be installed (e.g., Bash tool is restricted or `npm`/`brew` are unavailable).

## Before You Start

1. **Check the CLI is available** by running `renamed --version` via Bash.
   - If not found, try to install: `brew tap renamed-to/cli && brew install renamed` or `npm install -g @renamed-to/cli`.
   - If installation is not possible, fall back to MCP tools (`mcp__renamed-to__rename`).
2. **Check authentication**: run `renamed doctor` (CLI) or call `mcp__renamed-to__status` (MCP).
   - If not authenticated, direct the user to `renamed auth login`.
3. **Resolve file paths** from `$ARGUMENTS`. If the user provided a directory, use `Glob` to find supported files (PDF, JPG, JPEG, PNG, TIFF).

## CLI Reference

```
renamed rename [options] <files...>

Options:
  -a, --apply                 Apply the rename (without this, it only previews)
  -o, --output-dir <dir>      Output directory
  -p, --prompt <instruction>  Custom AI instruction for filename format
  -s, --strategy <name>       Folder organization strategy
  -t, --template <name>       Predefined filename template
  -l, --language <code>       Output language (en, de, fr, es, ...)
  --overwrite                 Overwrite existing files
  --on-conflict <mode>        fail (default), skip, or suffix
  --json                      Machine-readable JSON output
```

**Strategies:** `by_date`, `by_issuer`, `by_type`, `by_date_issuer`, `by_date_type`, `by_issuer_type`, `by_all`, `root`, `follow_custom_prompt`

**Templates:** `standard`, `date_first`, `company_first`, `minimal`, `detailed`, `department_focus`

## Workflow

### Single File

1. **Preview first** — always run without `-a` to show the suggested name:
   ```bash
   renamed rename invoice.pdf
   ```
2. Show the user the before/after preview from the output.
3. If the user approves, apply the rename:
   ```bash
   renamed rename -a invoice.pdf
   ```

### Batch Rename

1. **Preview the batch:**
   ```bash
   renamed rename *.pdf
   ```
   Or for a directory of mixed files:
   ```bash
   renamed rename ~/Documents/inbox/*.pdf ~/Documents/inbox/*.jpg
   ```
2. Show the full preview table to the user.
3. If approved, apply:
   ```bash
   renamed rename -a ~/Documents/inbox/*.pdf ~/Documents/inbox/*.jpg
   ```

### With JSON output (for programmatic use)

```bash
renamed rename --json invoice.pdf
renamed rename --json -a *.pdf
```

## Options to Offer

Only mention these if the user asks or the context calls for it:

- **Custom prompt**: `renamed rename -a -p "Format: YYYY-MM-DD_CompanyName_Type" invoice.pdf`
- **Strategy**: `renamed rename -a -s by_date -o ~/Documents invoice.pdf`
- **Template**: `renamed rename -a -t date_first invoice.pdf`
- **Language**: `renamed rename -a -l de invoice.pdf`
- **Conflict handling**: `renamed rename -a --on-conflict suffix *.pdf`

## Error Handling

- **CLI not found**: `brew tap renamed-to/cli && brew install renamed` or `npm install -g @renamed-to/cli`. If neither works, use MCP tools as fallback.
- **Not authenticated**: `renamed auth login`
- **Unsupported file type**: Tell the user which types are supported (PDF, JPG, JPEG, PNG, TIFF).
- **File too large**: Max 25MB per file.

## Tips

- Always preview before applying. The CLI defaults to preview mode (no `-a`), which is safe.
- For large batches, use `--json` output to parse results programmatically if needed.
- In a git repo, mention that `git mv` may be preferred to preserve history.
- The `--on-conflict suffix` flag is useful for batches where name collisions are likely.