Quick Start

Get up and running with AI Image Renamer CLI in under 5 minutes. This guide assumes you've already installed the tool and configured your API key.

Your First Rename

Let's rename a single image file:

rename-images photo.jpg

What happens:

1. The tool validates photo.jpg is a real image
2. Sends it to the AI for analysis
3. Receives a description like "sunset beach palm trees"
4. Renames the file to sunset-beach-palm-trees.jpg

Output:

Processing photo.jpg...
Renamed photo.jpg to /current/directory/sunset-beach-palm-trees.jpg

That's It!

One command, one renamed file. The AI does all the work of understanding what's in your image.

Renaming Multiple Images

Process several images at once by listing them:

rename-images photo1.jpg photo2.png photo3.webp

Output:

Processing photo1.jpg...
Renamed photo1.jpg to /path/family-picnic-sunny-day.jpg
Processing photo2.png...
Renamed photo2.png to /path/mountain-hiking-trail-forest.png
Processing photo3.webp...
Renamed photo3.webp to /path/city-skyline-night-lights.webp

Using Wildcards

Your shell can expand wildcards before passing files to the tool:

# Rename all JPEG files in current directory
rename-images *.jpg

# Rename all images in a folder
rename-images vacation-photos/*.jpg vacation-photos/*.png

Shell Expansion

The * wildcard is processed by your shell, not by the tool. For large numbers of files, you might see "argument list too long." In that case, use find and xargs.

Controlling Filename Length

Use the --words (or -w) option to control how descriptive your filenames are:

Short Filenames (3 words)

rename-images -w 3 IMG_2847.jpg

Result: sunset-beach.jpg

Good for simple images or when you want concise names.

Medium Filenames (6 words - default)

rename-images IMG_2847.jpg
# or explicitly
rename-images -w 6 IMG_2847.jpg

Result: sunset-beach-palm-trees-golden-hour.jpg

Balanced descriptiveness — the default setting.

Long Filenames (10 words)

rename-images -w 10 IMG_2847.jpg

Result: beautiful-sunset-over-tropical-beach-with-palm-trees-and-golden-light.jpg

Maximum detail for complex images.

AI Variation

The AI treats the word count as a guideline, not a strict limit. You might get 5 words when requesting 6, or 8 when requesting 10.

Real-World Example

Let's walk through organizing a vacation photo folder:

Starting State

vacation-2026/
├── IMG_0001.jpg
├── IMG_0002.jpg
├── IMG_0003.jpg
├── IMG_0004.jpg
└── IMG_0005.jpg

Running the Command

cd vacation-2026
rename-images *.jpg

After Renaming

vacation-2026/
├── beach-sunset-palm-trees-orange-sky.jpg
├── mountain-hiking-trail-forest-trees.jpg
├── city-street-night-neon-lights.jpg
├── family-dinner-restaurant-smiling-faces.jpg
└── ocean-waves-crashing-rocks-blue-water.jpg

Now you can find specific photos just by reading the filenames!

Checking the Version

To see which version you have installed:

rename-images --version
# or
rename-images -v

Output:

rename-images 1.1.0

Getting Help

View all available options:

rename-images --help
# or
rename-images -h

Output:

usage: rename-images [-h] [-v] [-w N] image_paths [image_paths ...]

AI Image Renamer CLI - Rename images using AI-generated descriptions

positional arguments:
  image_paths      Path(s) to the image file(s) to be renamed.

options:
  -h, --help       show this help message and exit
  -v, --version    Show the version of ai-image-renamer and exit
  -w N, --words N  Number of words to use in the generated filename. (default: 6)

Processing Many Files

For hundreds or thousands of images, use find and xargs:

# Find all JPEGs and process them in batches
find . -name "*.jpg" -print0 | xargs -0 rename-images

What this does:

• find . -name "*.jpg" — finds all .jpg files in current directory and subdirectories
• -print0 — handles filenames with spaces correctly
• xargs -0 — passes files to rename-images in batches
• rename-images — processes each batch

Common Patterns

Organize Screenshots

# Rename all screenshots in a folder
rename-images Screenshot*.png

Process Camera Photos

# Rename all photos from a camera's DCIM folder
rename-images /media/camera/DCIM/100CANON/*.jpg

Prepare Images for Web

# Create short, web-friendly names
rename-images -w 4 uploads/*.jpg

What's Next?

• Command Options — Detailed option reference
• Environment Variables — Advanced configuration
• API Reference — Use the tool programmatically