renamr

renamr is a fast, intuitive, and robust bulk file renaming tool for the command line. Designed with efficiency and simplicity in mind, it allows developers and power users to perform complex renaming operations across thousands of files instantly.

🚀 Features

• Expressive Syntax: Simple commands to replace text, modify extensions, and manipulate casing.
• Works from anywhere: cd into any folder and run commands — no need to specify a path. Renamr targets the current directory by default.
• Dry Run Support: Preview all your renaming operations safely before applying any changes using the --dry-run flag.
• Recursive Operations: Seamlessly rename files nested deeply within complex directory structures.
• Cross-Platform: Built on Node.js, ensuring consistent behavior across Windows, macOS, and Linux.

📦 Installation

Install renamr globally via npm to access it continuously from anywhere on your system:

npm install -g renamr

🛠️ Usage Guide

Renamr works in two ways — from the current directory (no path needed) or with an explicit path or glob:

# From the current directory (cd into your folder first)
renamr <command> [options]

# Or pass a specific file, folder, or glob pattern
renamr <command> [options] <files...>

Commands

Text Replacement (change)

Seamlessly replace occurrences of a string within file names.

# From current directory
renamr change "old-text" -w "new-text"

# With explicit path or glob
renamr change "old-text" -w "new-text" ./src/**/*

File Content Replacement (content or rewrite)

Search and replace text inside the contents of files instead of just renaming the files.

# From current directory
renamr content "music player" -w "video player"

# With explicit glob
renamr content "music player" -w "video player" ./**/* --recursive

Extension Modification (ext)

Quickly standardize or convert file extensions across your project.

# Specific file
renamr ext hello.js -w .ts

# All .js files in current directory
renamr ext *.js -w .ts

# With glob path
renamr ext ./src/**/*.js -w .ts

Add Prefix (prefix)

Prepend a consistent string to the beginning of matched file names.

# From current directory
renamr prefix "img_"

# With explicit glob
renamr prefix "img_" ./assets/*.png

Add Suffix (suffix)

Append a string to matched file names, inserted correctly right before the file extension.

# From current directory
renamr suffix "_v2"

# With explicit glob
renamr suffix "_v2" ./data/*.json

Case Conversions (lowercase & uppercase)

Standardize naming conventions by applying lower or upper casing to file names. Both commands support shorthand aliases (low and upp).

# Convert all files in current directory to lowercase
renamr low

# Or with an explicit path
renamr low ./dist/**/* --recursive

# Uppercase with explicit path
renamr upp ./src/**/* --recursive

⚙️ Configuration Flags

| Flag | Shorthand | Description | | :--- | :-------- | :---------- | | --with <value> | -w | Required for replace and ext commands. Specifies the replacement string or new extension. | | --dry-run | -d | Safe Mode: Previews changes in the console without actually renaming any files. Highly recommended before destructive actions. | | --recursive | -r | Executes the command recursively across all subdirectories matching the glob pattern. |

💡 Practical Examples

Safe preview of an architectural refactor:

renamr change "component" -w "widget" ./src/**/* --dry-run

Migrating a legacy JavaScript codebase to TypeScript:

renamr ext ./src/**/*.js -w .ts

Batch renaming user uploads with a timestamp:

renamr prefix "upload_2024_" ./public/uploads/*

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.