Command Options

This page documents all command-line options available for the rename-images command.

Synopsis

rename-images [OPTIONS] IMAGE_PATH [IMAGE_PATH ...]

Positional Arguments

image_paths (Required)

One or more paths to image files you want to rename.

Syntax: One or more file paths, separated by spaces.

Examples:

# Single file
rename-images photo.jpg

# Multiple files
rename-images photo1.jpg photo2.png photo3.webp

# Using wildcards (shell expansion)
rename-images *.jpg
rename-images images/*.png

Supported Formats:

• .jpg, .jpeg — JPEG images
• .png — PNG images
• .webp — WebP images
• .gif — GIF images (including animated)

Relative vs Absolute Paths

Both work fine. The tool converts relative paths to absolute paths internally.

Options

--words, -w (Optional)

Controls the maximum number of words in the generated filename.

Syntax: -w N or --words N where N is an integer from 1 to 49.

Default: 6

Purpose:

• Lower values (1-3): Shorter, more concise filenames
• Higher values (10+): More detailed, descriptive filenames

Examples:

# Short filenames (3 words max)
rename-images -w 3 photo.jpg
# Result: sunset-beach.jpg

# Default length (6 words)
rename-images photo.jpg
# Result: beautiful-sunset-beach-palm-trees.jpg

# Long filenames (12 words)
rename-images -w 12 photo.jpg
# Result: stunning-golden-sunset-over-tropical-beach-with-palm-trees-silhouettes.jpg

Not a Hard Limit

The AI treats this as a guideline. Actual word count may vary slightly. The AI might return 5 words when you request 6, or 7 words when you request 5.

--version, -v (Optional)

Displays the installed version and exits immediately.

Syntax: -v or --version

Example:

rename-images --version

Output:

rename-images 1.1.0

Note: No image processing occurs when using this option.

--help, -h (Optional)

Displays usage information and exits immediately.

Syntax: -h or --help

Example:

rename-images --help

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. Accepts multiple
                   files. Supported formats: JPEG, PNG, WebP, GIF, and others
                   detected by content.

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. Shorter
                   filenames are more concise; longer are more descriptive.
                   (default: 6)

Option Combinations

Options can be combined in any order:

# Both must appear before image paths
rename-images -w 5 photo.jpg
rename-images photo.jpg -w 5  # Also works

# Multiple options
rename-images -v  # Only shows version, ignores other args

Exit Codes

The command returns different exit codes to indicate success or failure:

Code	Meaning	Description
0	Success	All images processed successfully
1	Error	Invalid arguments or missing files
2	RuntimeError	GROQ_API_KEY not set
130	Interrupted	User pressed Ctrl+C

Checking Exit Codes:

rename-images photo.jpg
echo $?  # Prints the exit code

Usage Examples

Basic Usage

# Rename single image with default 6 words
rename-images vacation.jpg

# Rename multiple images
rename-images img1.jpg img2.png img3.webp

# Use wildcard expansion
rename-images photos/*.jpg

Short Filenames

# Concise 3-word names
rename-images -w 3 *.jpg

# Minimal 2-word names
rename-images -w 2 screenshots/*.png

Detailed Filenames

# Detailed 10-word descriptions
rename-images -w 10 wedding-photos/*.jpg

# Maximum detail
rename-images -w 20 nature-photos/*.jpg

Batch Processing

# Process all images in subdirectories
find . -type f \( -name "*.jpg" -o -name "*.png" \) -print0 | xargs -0 rename-images

# Process with custom word count
find photos -name "*.jpg" -print0 | xargs -0 rename-images -w 4

Error Handling

# Continue processing even if some files fail
rename-images valid.jpg invalid.pdf another.jpg
# Output:
# Processing valid.jpg...
# Renamed valid.jpg to /path/description.jpg
# Skipping invalid image file: invalid.pdf
# Processing another.jpg...
# Renamed another.jpg to /path/another-description.jpg

Limitations

File Size

There's no explicit file size limit, but very large images (10+ MB) may:

• Take longer to encode and upload
• Hit API timeout limits
• Consume more of your Groq token allowance

Rate Limits

Groq's free tier has rate limits:

• 30 requests per minute
• 7,000 tokens per minute

If you hit these limits, wait a minute and retry. The tool doesn't currently implement automatic retries.

Concurrent Files

Files are processed sequentially, not in parallel. This is intentional to:

• Stay within API rate limits
• Provide clear, ordered output
• Simplify error handling

Advanced Patterns

Conditional Processing

# Only process files modified in the last 7 days
find . -name "*.jpg" -mtime -7 -print0 | xargs -0 rename-images

Logging Output

# Save output to a log file
rename-images *.jpg 2>&1 | tee rename-log.txt

Dry Run (Simulation)

The tool doesn't have a built-in dry-run mode, but you can preview filenames:

# List files that would be processed
ls *.jpg

# Process one file to see the AI output style
rename-images sample.jpg

Related Topics

• Quick Start Guide — Get started quickly
• Environment Variables — Configure API settings
• Troubleshooting — Solve common problems