imgconvert-cli
Advanced tools
imgconvert-cli is a powerful command-line tool for compressing, converting, and resizing images using the sharp library. It supports various formats and lets you optimize images for the web or other purposes, with customizable quality, background color, advanced resizing strategies, and multi-format conversion.
# Install globally
npm install -g imgconvert-cli
# Compress images (preserves original format)
imgconvert my-images
# Convert to WebP with 80% quality
imgconvert my-images -f webp -q 80
# Advanced resizing with cover strategy (crops to fill dimensions)
imgconvert photo.jpg --fit cover --position center -w 400 -h 400 -f webp
# Manual cropping: extract specific region then resize
imgconvert photo.jpg --crop 100,50,800,600 -w 400 -h 300 -f webp
# Canvas resize: maintain original image, add transparent padding
imgconvert photo.png --canvas -h 1660
imgconvert design.png --canvas -w 800 -h 600 -f webp
# Custom file naming and batch renaming
imgconvert photo.jpg --name "hero-banner" -f webp
imgconvert photos --rename "lowercase,replace-spaces,prefix:web-" -f webp
# Generate mobile app assets (all configurations)
imgconvert source-images -p alloy
# Generate specific mobile app assets (user-defined configurations)
imgconvert -p alloy:your-config-name
imgconvert -p alloy:another-config
--fit cover with --position for consistent square thumbnails--canvas to maintain original images while extending to exact canvas dimensions--canvasimgconvert -p alloy:config-name to update only specific user-defined asset categories--cropTypical compression results:
sharp to apply compression, format conversion, resizing, and optional background colorimage.jpg → image.jpg)image.jpg -f webp → image.webp)converted subfolder by default, or replaces original files if --replace-originals is usednpm install -g imgconvert-cli
# or
yarn global add imgconvert-cli
imgconvert --version
imgconvert <source_path>
<source_path>: The path to the image file or directory containing the images you want to process. This is a required positional argument.📝 Important: When you don't specify the
-f/--formatoption, each output image will preserve its original file extension. For example:
image.jpg→image.jpg(compressed but same format)image.png→image.png(compressed but same format)The file extension only changes when you explicitly specify a different format with
-f.
The available options for the imgconvert-cli command let users customize image conversions easily.
| Option | Alias | Description | Default |
|---|---|---|---|
--format | -f | Output format: jpeg, png, webp, avif, tiff, gif, all | Original format |
--quality | -q | Quality (1-100) | 85 |
--background | -b | Background color when converting from transparent formats to non-transparent formats | Transparent for PNG/WebP, #ffffff for JPEG |
--width | -w | Output width in pixels | - |
--height | -h | Output height in pixels | - |
--output | -o | Output directory | Same as source |
--preset | -p | Apply preset: web, print, thumbnail, alloy | - |
--fit | - | Resize strategy: cover, contain, fill, inside, outside | contain |
--position | - | Crop position: center, top, bottom, left, right, corners | center |
--crop | - | Manual crop coordinates: left,top,width,height | - |
--canvas | - | Resize canvas instead of image (maintains original, adds padding) | false |
--name | -n | Custom filename for single file processing | - |
--rename | - | Batch rename strategy: enumerate, lowercase, replace-spaces, prefix:, suffix: | - |
--replace-originals | - | Replace original files | false |
--debug | -d | Enable debug mode | false |
--version | -v | Show version | - |
--help | -H | Show help message | - |
The Sharp library integration provides powerful image manipulation capabilities with precise control over how images are resized and cropped.
Processing Workflow: Manual Crop → Resize → Format Conversion
--fit)Controls how images are resized when both width and height are specified:
| Strategy | Behavior | Use Case | Aspect Ratio |
|---|---|---|---|
contain | Shrink to fit, letterbox if needed | Preserve entire image | Preserved |
cover | Crop to fill dimensions exactly | Hero images, thumbnails | Preserved |
fill | Stretch to exact dimensions | Icons, backgrounds | Ignored |
inside | Only shrink, never enlarge | High-res source images | Preserved |
outside | Only enlarge, never shrink | Upscaling small images | Preserved |
--position)When using --fit cover, controls which part of the image to preserve:
| Position | Description | Best For |
|---|---|---|
center | Focus on center (default) | General purpose |
top | Focus on top edge | Portraits, faces |
bottom | Focus on bottom edge | Architecture |
left | Focus on left edge | Portraits (left-facing) |
right | Focus on right edge | Portraits (right-facing) |
top left | Focus on top-left corner | Documents, logos |
top right | Focus on top-right corner | UI screenshots |
bottom left | Focus on bottom-left corner | Signatures |
bottom right | Focus on bottom-right corner | Watermarks |
--crop)Extract specific regions before resizing:
left,top,width,height (all in pixels)--crop 100,50,800,600 crops 800x600 region starting at (100,50)--canvas)Choose between two different resizing approaches:
imgconvert photo.png -h 1660
# 1024x1536 → 1107x1660 (proportional scaling)
--canvas)imgconvert photo.png --canvas -h 1660
# 1024x1536 → 1024x1660 (original image + transparent padding)
imgconvert photo.png --canvas -h 1660 -b "#ff0000"
# 1024x1536 → 1024x1660 (original image + red padding)
| Aspect | Standard Resize | Canvas Resize (--canvas) |
|---|---|---|
| Image scaling | ✅ Scales proportionally | ❌ Maintains original size |
| Exact dimensions | ❌ Respects aspect ratio | ✅ Exact target dimensions |
| Transparency | Preserves existing | ✅ Adds transparent padding |
| Use case | Photo resizing | Design layouts, mockups |
The tool provides flexible options for customizing output filenames when processing images.
--name, -n)Rename individual files during processing:
imgconvert photo.jpg --name "hero-image" -f webp
# Output: hero-image.webp
Important: The --name option only works with single files, not directories.
--rename)Apply systematic renaming to multiple files:
| Strategy | Description | Example Input | Example Output |
|---|---|---|---|
enumerate | Add sequential numbers | photo.jpg | 001-photo.jpg |
lowercase | Convert to lowercase | MyPhoto.JPG | myphoto.jpg |
replace-spaces | Replace spaces with hyphens | my photo.png | my-photo.png |
prefix:text | Add prefix to filename | image.jpg | thumb-image.jpg |
suffix:text | Add suffix to filename | image.jpg | image-small.jpg |
Multiple rename strategies can be combined by separating them with commas:
imgconvert photos --rename "lowercase,replace-spaces,prefix:web-"
# "My Photo.jpg" → "web-my-photo.jpg"
imgconvert images --rename "enumerate,suffix:-optimized"
# "photo.jpg" → "001-photo-optimized.jpg"
Processing Order: Strategies are applied in the order specified, allowing for predictable filename transformations.
Compress images without changing format (preserves extensions):
imgconvert image.jpg # → image.jpg (compressed)
imgconvert image.png # → image.png (compressed)
Compress all images in directory (preserves original formats):
imgconvert source_folder # Each file keeps its original extension
Convert to different format (changes extension):
imgconvert image.jpg -f webp -q 75 # → image.webp
imgconvert image.png -f jpeg # → image.jpeg
Smart resizing strategies:
# Cover strategy: crop to fill exact dimensions
imgconvert photo.jpg --fit cover -w 400 -h 400
# Contain strategy: fit inside dimensions (default)
imgconvert photo.jpg --fit contain -w 400 -h 400
# Fill strategy: stretch to exact dimensions
imgconvert photo.jpg --fit fill -w 400 -h 400
Control cropping position with cover strategy:
# Keep the top part when cropping
imgconvert portrait.jpg --fit cover --position top -w 300 -h 300
# Keep the center (default)
imgconvert photo.jpg --fit cover --position center -w 300 -h 300
# Keep specific corners
imgconvert image.jpg --fit cover --position "top left" -w 400 -h 400
Manual cropping before resizing:
# Crop specific region then resize
imgconvert image.png --crop 100,50,300,200 -w 200 -h 150
# Crop and convert format
imgconvert photo.jpg --crop 0,0,500,500 --fit cover -w 300 -h 300 -f webp
Canvas resizing (maintain original image, add padding):
# Resize canvas to larger dimensions with transparent padding
imgconvert photo.png --canvas -h 1660
# Original 1024x1536 → Output 1024x1660 with transparent padding
# Resize canvas with custom background color
imgconvert photo.png --canvas -h 1660 -b "#ffffff"
# Adds white padding instead of transparent
# Resize canvas to exact dimensions
imgconvert image.jpg --canvas -w 800 -h 600 -f png
# Maintains original image centered, adds transparent padding to reach 800x600
Custom naming for single files:
# Rename during conversion
imgconvert hero-photo.jpg --name "main-banner" -f webp
# Output: main-banner.webp
# Custom name with resizing
imgconvert profile.png --name "avatar" --fit cover -w 200 -h 200
# Output: avatar.png
Batch renaming strategies:
# Add sequential numbers
imgconvert photos --rename enumerate -f webp
# photo1.jpg → photo1-1.webp, photo2.jpg → photo2-2.webp
# Convert to lowercase and replace spaces
imgconvert "My Photos" --rename "lowercase,replace-spaces"
# "My Photo.JPG" → "my-photo.jpg"
# Add prefix for organization
imgconvert thumbnails --rename "prefix:thumb-" -w 150 -h 150
# image.jpg → thumb-image.jpg
Advanced renaming combinations:
# Multiple strategies for web optimization
imgconvert uploads --rename "lowercase,replace-spaces,suffix:-optimized" -f webp -q 80
# "Product Photo.png" → "product-photo-optimized.webp"
# Enumerated thumbnails with prefix
imgconvert gallery --rename "prefix:gallery-,enumerate" --fit cover -w 300 -h 300
# photo.jpg → gallery-001-photo.jpg
Perfect for web development:
# Social media thumbnails with organized naming
imgconvert profiles --fit cover --position top -w 150 -h 150 -f webp --rename "prefix:profile-,enumerate"
# Product images with consistent dimensions and clean filenames
imgconvert products --fit contain -w 800 -h 600 -f webp -q 90 --rename "lowercase,replace-spaces"
# Hero banners with descriptive names
imgconvert heroes --fit cover --position center -w 1920 -h 800 -f webp --rename "suffix:-hero"
Mobile app assets with systematic naming:
# Square app icons with size indicators
imgconvert icons --fit cover --position center -w 512 -h 512 -f png --rename "suffix:-512"
# Profile pictures with enumeration
imgconvert avatars --fit cover --position top -w 200 -h 200 -f webp --rename "prefix:avatar-,enumerate"
E-commerce and content management:
# Product catalog with clean, SEO-friendly names
imgconvert "Product Photos" --rename "lowercase,replace-spaces,prefix:product-" -f webp -q 85
# "Blue Shirt Medium.jpg" → "product-blue-shirt-medium.webp"
# Blog post images with consistent naming
imgconvert blog-images --rename "lowercase,replace-spaces,suffix:-post" -w 800 -q 80
# "My Great Article Photo.png" → "my-great-article-photo-post.png"
imgconvert avatars --fit cover --position top -w 200 -h 200 -f webp
Use alloy preset with platform-specific formats:
imgconvert source_folder -p alloy
# Generates images for ALL configurations (comics, thumbs-comics, baby, thumbs-baby)
Process specific alloy configurations (user-defined):
imgconvert -p alloy:your-cards-config
# Processes ONLY the 'your-cards-config' configuration (both Android and iPhone)
# Note: 'your-cards-config' must be defined in your .imgconverter.config.json
imgconvert -p alloy:your-thumbnails-config
# Processes ONLY the 'your-thumbnails-config' configuration
# Note: 'your-thumbnails-config' must be defined in your .imgconverter.config.json
imgconvert -p alloy:your-icons-config
# Processes ONLY the 'your-icons-config' configuration
# Note: 'your-icons-config' must be defined in your .imgconverter.config.json
Override preset settings with CLI arguments:
imgconvert source_folder -p alloy -f png -q 95
# CLI arguments override preset: both Android and iPhone will use PNG at 95% quality
imgconvert -p alloy:your-cards-config -q 90
# Only 'your-cards-config' configuration with 90% quality override
# Note: 'your-cards-config' must be defined in your .imgconverter.config.json
Use preset settings with partial CLI override:
imgconvert source_folder -p alloy -q 80
# Only quality is overridden: Android uses WebP, iPhone uses PNG, both at 80% quality
imgconvert -p alloy:your-config-name -f webp
# Only your-config-name configuration, forced to WebP format for both platforms
# Note: 'your-config-name' must be defined in your .imgconverter.config.json
Extract and optimize specific image regions with manual cropping:
# Extract a product from a larger photo and create web-optimized thumbnails
imgconvert product-photo.jpg --crop 200,150,600,800 -w 300 -h 400 -f webp -q 85
# Create hero image by cropping center portion from high-res photo
imgconvert landscape.jpg --crop 500,100,1920,800 --fit cover -w 1200 -h 500 -f webp
# Extract faces from group photos for profile pictures
imgconvert group-photo.jpg --crop 350,200,500,500 --fit cover -w 150 -h 150 -f webp
Specify a custom output directory:
imgconvert source_folder -o custom_output_directory
Enable debug mode:
imgconvert source_folder -d
Check the version of the module:
imgconvert --version
Show help message:
imgconvert --help
imgconvert-cli has intelligent file extension handling:
When no format is specified with -f, the original file extension is preserved:
| Input | Command | Output |
|---|---|---|
logo.png | imgconvert logo.png | logo.png |
icon.webp | imgconvert icon.webp | icon.webp |
photo.jpg | imgconvert photo.jpg | photo.jpg |
When using -f to specify a format, the extension changes accordingly:
| Input | Command | Output |
|---|---|---|
logo.png | imgconvert logo.png -f jpeg | logo.jpeg |
icon.webp | imgconvert icon.webp -f png | icon.png |
photo.jpg | imgconvert photo.jpg -f webp | photo.webp |
💡 Tip: This behavior ensures consistency and user expectations while maintaining technical compatibility with the Sharp image processing library.
Presets are predefined configurations for common use cases:
webp, quality 80). Optionally defines a source path.tiff, quality 100). Optionally defines a source path.png, quality 60, 150x150). Optionally defines a source path.webp, quality 80, 300x300). Optionally defines a source path.webp, quality 85, 1920x1080). Optionally defines a source path.source path. You can process all configurations with -p alloy or target specific ones with -p alloy:configName where configName is your custom configuration defined in .imgconverter.config.json.Beyond the built-in presets, you can create your own custom presets in the .imgconverter.config.json file. This allows you to define reusable configurations for specific workflows or project requirements.
{
"presets": {
"instagram-post": {
"width": 1080,
"height": 1080,
"quality": 85,
"format": "jpeg",
"background": "#ffffff"
},
"email-newsletter": {
"width": 600,
"quality": 70,
"format": "jpeg",
"output": "email/assets",
"source": "content/images"
},
"product-catalog": {
"width": 800,
"height": 800,
"quality": 90,
"format": "webp",
"background": "#ffffff"
}
}
}
# Use your custom presets
imgconvert photos -p instagram-post
imgconvert products -p product-catalog
imgconvert banner.png -p email-newsletter
# Override preset settings with CLI arguments
imgconvert photos -p instagram-post -q 95 # Uses Instagram preset but with 95% quality
# Use selective configuration with custom alloy presets
imgconvert -p alloy:your-game-cards # Process only your-game-cards configuration
imgconvert -p alloy:your-config-name -q 90 # Process only your-config-name with custom quality
# Note: These configurations must be defined in your .imgconverter.config.json
📖 Complete Custom Presets Guide - See advanced examples, best practices, and complex workflows including social media, e-commerce, email marketing, and development environment presets.
| Feature | imgconvert-cli | ImageMagick | Sharp CLI |
|---|---|---|---|
| Easy Setup | ✅ | ❌ | ✅ |
| Batch Processing | ✅ | ✅ | ❌ |
| Mobile Presets | ✅ | ❌ | ❌ |
| Custom Presets | ✅ | ❌ | ❌ |
| Config File | ✅ | ❌ | ❌ |
| Extension Preservation | ✅ | ❌ | ❌ |
| Multi-Format Output | ✅ | ✅ | ❌ |
| Comprehensive Tests | ✅ | ❌ | ❌ |
The alloy preset is specifically designed for mobile app development with Titanium Alloy framework. It generates multiple scaled versions of images for both Android and iOS platforms.
width and height parameters are ignored as images are scaled proportionallyalloy:configName syntax for efficient workflowsThe alloy preset now supports targeting specific configurations, which is perfect for:
Examples:
# Process all configurations (default behavior)
imgconvert -p alloy
# Process only your custom assets configuration
imgconvert -p alloy:your-config-name
# Process only your thumbnail variants (user-defined configurations)
imgconvert -p alloy:your-thumbs-config1
imgconvert -p alloy:your-thumbs-config2
# Perfect for adding new categories
imgconvert -p alloy:your-new-category # Only process your custom 'new-category' configuration
# Note: All configuration names must be defined in your .imgconverter.config.json
Scale factors are immutable constants that follow Titanium platform standards and cannot be modified:
🔒 Note: Scale factors are fixed to ensure Titanium compatibility and cannot be customized. This prevents configuration errors and maintains consistency with Titanium SDK requirements.
# Legacy format (single android/iphone configuration)
imgconvert source-images -p alloy
# Multi-configuration format (all configuration groups)
imgconvert -p alloy
# Process only your custom configuration
imgconvert -p alloy:your-config-name
# Process only your custom thumbnail configurations
imgconvert -p alloy:your-thumbs-config1
imgconvert -p alloy:your-thumbs-config2
# Process only your custom configuration
imgconvert -p alloy:another-config-name
# Note: All configuration names must be defined in your .imgconverter.config.json
imgconvert source-images -p alloy
imgconvert -p alloy
Note: With multi-configuration format, all configuration groups are processed automatically from their respective source directories when using
-p alloy, or you can target specific configurations using-p alloy:configName.
Note: When using the alloy preset,
widthandheightparameters are automatically ignored since images are scaled based on predefined factors to maintain mobile platform standards.
When using the alloy preset, the output base path is always fixed:
app/assets/android/imagesapp/assets/iphone/imagesYou only need to specify the relative subfolder (without leading or trailing slashes, e.g. thumbs/baby) as the output in the preset or CLI. The script will generate the correct structure for each density:
Correct usage:
"output": "thumbs/baby"
Do NOT use:
/thumbs/babythumbs/baby//thumbs/baby/Android Example:
app/assets/android/images/res-mdpi/thumbs/baby/logo.png
app/assets/android/images/res-hdpi/thumbs/baby/logo.png
app/assets/android/images/res-xhdpi/thumbs/baby/logo.png
app/assets/android/images/res-xxhdpi/thumbs/baby/logo.png
app/assets/android/images/res-xxxhdpi/thumbs/baby/logo.png
iPhone Example:
app/assets/iphone/images/thumbs/baby/logo.png
app/assets/iphone/images/thumbs/baby/logo@2x.png
app/assets/iphone/images/thumbs/baby/logo@3x.png
You do not need to specify the full output path, just the subfolder as shown above. The script will handle the rest.
The alloy preset supports two configuration formats:
Each platform (android/iphone) has its own source directory:
"presets": {
"alloy": {
"android": {
"output": "thumbs/baby",
"source": "android-source-folder"
},
"iphone": {
"output": "thumbs/baby",
"source": "iphone-source-folder"
}
}
}
🔒 Note: Scale factors are immutable and automatically applied based on Titanium standards. The
scalesproperty is no longer supported.
Multiple configuration groups with independent source/output management:
"presets": {
"alloy": {
"cards": {
"android": {
"quality": 90,
"format": "webp",
"source": "originals",
"output": "cards/baby"
},
"iphone": {
"quality": 90,
"format": "webp",
"source": "originals",
"output": "cards/baby"
}
},
"thumbs": {
"android": {
"quality": 80,
"format": "webp",
"output": "thumbs/baby",
"source": "original-thumbs"
},
"iphone": {
"quality": 80,
"format": "webp",
"output": "thumbs/baby",
"source": "original-thumbs"
}
},
"icons": {
"android": {
"quality": 95,
"format": "png",
"output": "icons",
"source": "icons-4x"
},
"iphone": {
"quality": 95,
"format": "png",
"output": "icons",
"source": "icons-4x"
}
}
}
}
Benefits of Multi-Configuration Format:
Then you can simply run:
imgconvert -p alloy
The tool will automatically:
-d flagMulti-Configuration Debug Output Example:
Processing configuration: cards
Processing android from: originals
Processing iphone from: originals
Processing configuration: thumbs
Processing android from: original-thumbs
Processing iphone from: original-thumbs
Processed files:
- app/assets/android/images/res-mdpi/cards/baby/card1.webp (config: cards, platform: android, scale: res-mdpi)
- app/assets/android/images/res-hdpi/cards/baby/card1.webp (config: cards, platform: android, scale: res-hdpi)
- app/assets/iphone/images/cards/baby/card1.webp (config: cards, platform: iphone, scale: 1x)
- app/assets/iphone/images/cards/baby/card1@2x.webp (config: cards, platform: iphone, scale: 2x)
- app/assets/android/images/res-mdpi/thumbs/baby/thumb1.webp (config: thumbs, platform: android, scale: res-mdpi)
...
Processing complete! Summary:
- Processed files: 24
- Total original size: 2.45 MB
- Total new size: 0.89 MB
- Total savings: 63.67%
- Duration: 1.24 seconds
Let's say you're developing a card game and have the following directory structure:
my-game/
├── originals/ # 4x resolution card images
│ ├── card1.png
│ ├── card2.png
│ └── card3.png
├── original-thumbs/ # 4x resolution thumbnail images
│ ├── card1.png
│ ├── card2.png
│ └── card3.png
├── icons-4x/ # 4x resolution icon images
│ ├── star.png
│ ├── coin.png
│ └── heart.png
└── .imgconverter.config.json
With this multi-configuration setup in your .imgconverter.config.json:
{
"presets": {
"alloy": {
"cards": {
"android": {
"quality": 90,
"format": "webp",
"source": "originals",
"output": "cards/baby"
},
"iphone": {
"quality": 90,
"format": "webp",
"source": "originals",
"output": "cards/baby"
}
},
"thumbs": {
"android": {
"quality": 80,
"format": "webp",
"output": "thumbs/baby",
"source": "original-thumbs"
},
"iphone": {
"quality": 80,
"format": "webp",
"output": "thumbs/baby",
"source": "original-thumbs"
}
},
"icons": {
"android": {
"quality": 95,
"format": "png",
"output": "icons",
"source": "icons-4x"
},
"iphone": {
"quality": 95,
"format": "png",
"output": "icons",
"source": "icons-4x"
}
}
}
}
}
Run a single command:
imgconvert -p alloy
And get all these files automatically generated:
app/
└── assets/
├── android/
│ └── images/
│ ├── res-mdpi/
│ │ ├── cards/baby/card1.webp (1x)
│ │ ├── thumbs/baby/card1.webp (1x)
│ │ └── icons/star.png (1x)
│ ├── res-hdpi/
│ │ ├── cards/baby/card1.webp (1.5x)
│ │ ├── thumbs/baby/card1.webp (1.5x)
│ │ └── icons/star.png (1.5x)
│ ├── res-xhdpi/
│ │ ├── cards/baby/card1.webp (2x)
│ │ ├── thumbs/baby/card1.webp (2x)
│ │ └── icons/star.png (2x)
│ ├── res-xxhdpi/
│ │ ├── cards/baby/card1.webp (3x)
│ │ ├── thumbs/baby/card1.webp (3x)
│ │ └── icons/star.png (3x)
│ └── res-xxxhdpi/
│ ├── cards/baby/card1.webp (4x)
│ ├── thumbs/baby/card1.webp (4x)
│ └── icons/star.png (4x)
└── iphone/
└── images/
├── cards/baby/
│ ├── card1.webp (1x)
│ ├── card1@2x.webp (2x)
│ └── card1@3x.webp (3x)
├── thumbs/baby/
│ ├── card1.webp (1x)
│ ├── card1@2x.webp (2x)
│ └── card1@3x.webp (3x)
└── icons/
├── star.png (1x)
├── star@2x.png (2x)
└── star@3x.png (3x)
Advantages:
1. Development Phase:
# Test only what you're working on
imgconvert -p alloy:comics -d # Enable debug mode to see detailed processing
2. Adding New Asset Categories:
# First, add your new configuration to .imgconverter.config.json
# Then process only the new category
imgconvert -p alloy:new-category
3. Quality Testing:
# Test different quality settings for specific configurations
imgconvert -p alloy:comics -q 95 # Higher quality for main assets
imgconvert -p alloy:thumbs-comics -q 60 # Lower quality for thumbnails
4. CI/CD Integration:
# Process only changed asset categories in your build pipeline
if [[ "$CHANGED_ASSETS" == *"comics"* ]]; then
imgconvert -p alloy:comics
fi
-d) to monitor processing details-p alloy) only for final buildsThe configuration file .imgconverter.config.json allows you to define global default parameters and custom presets for image processing.
Quick Start: You can generate a default configuration file at any time by running:
imgconvert config
The tool follows a consistent 4-level precedence system for all configuration parameters:
.imgconverter.config.json fileThis means CLI arguments always override preset settings, preset settings override global config, and global config overrides defaults. This precedence applies to all parameters: quality, format, width, height, output, replace-originals, background, fit, position, and crop.
cover, contain, fill, inside, outside).fit: cover (center, top, bottom, left, right, corners).left,top,width,height.null, defaults to a converted directory at the same level as the source path.format, quality, width, height, output, source, fit, position, and crop. All preset configurations follow the precedence system: CLI arguments always override preset values, which override global config values.{
"width": null,
"height": null,
"quality": 85,
"source": null,
"output": null,
"format": null,
"replace": false,
"background": "#ffffff",
"presets": {
"web": { "source": null, "format": "webp", "quality": 80 },
"print": { "source": null, "format": "tiff", "quality": 100 },
"thumbnail": { "source": null, "format": "png", "quality": 60, "width": 150, "height": 150 },
"alloy": {
"android": {
"source": null,
"output": "./app/assets/android/images",
"scales": { "res-mdpi": 1, "res-hdpi": 1.5, "res-xhdpi": 2, "res-xxhdpi": 3, "res-xxxhdpi": 4 }
},
"iphone": {
"source": null,
"output": "./app/assets/iphone/images",
"scales": { "1x": 1, "2x": 2, "3x": 3 }
}
}
}
}
{
"width": null,
"height": null,
"quality": 85,
"fit": "contain",
"position": "center",
"crop": null,
"source": null,
"output": null,
"format": null,
"background": null,
"replace-originals": false,
"presets": {
"web": { "source": null, "output": null, "format": "webp", "quality": 80 },
"print": { "source": null, "output": null, "format": "tiff", "quality": 100 },
"thumbnail": { "source": null, "output": null, "format": "png", "quality": 60, "width": 150, "height": 150 },
"alloy": {
"cards": {
"android": {
"quality": 90,
"format": "webp",
"source": "originals",
"output": "cards/baby"
},
"iphone": {
"quality": 90,
"format": "webp",
"source": "originals",
"output": "cards/baby"
}
},
"thumbs": {
"android": {
"quality": 80,
"format": "webp",
"output": "thumbs/baby",
"source": "original-thumbs"
},
"iphone": {
"quality": 80,
"format": "webp",
"output": "thumbs/baby",
"source": "original-thumbs"
}
}
}
}
}
Note for Alloy Preset: The
outputvalue should only contain the relative subfolder path (e.g.,"thumbs/baby"), not the complete path. The base paths (app/assets/android/imagesandapp/assets/iphone/images) are automatically handled by the tool.
Example: How Precedence Works with Multi-Configuration
Given this configuration file:
{
"quality": 75,
"format": "jpeg",
"presets": {
"alloy": {
"cards": {
"android": {
"quality": 90,
"format": "webp"
},
"iphone": {
"quality": 95,
"format": "png"
}
},
"thumbs": {
"android": {
"quality": 70,
"format": "webp"
},
"iphone": {
"quality": 75,
"format": "webp"
}
}
}
}
}
Different command scenarios would result in:
imgconvert -p alloy →
imgconvert -p alloy -q 80 → All platforms and configurations use JPEG at 80% (CLI overrides everything)imgconvert -p alloy -f jpeg →
imgconvert -p alloy -f webp -q 85 → All platforms and configurations use WebP at 85% (CLI overrides everything)When debug mode is enabled with the -d or --debug option, the tool displays detailed information about the processing, including configuration-specific details for alloy presets.
Sample Debug Output (Standard Processing):
Processing complete! Summary:
- Processed files: 5
- Total original size: 0.87 MB
- Total new size: 0.25 MB
- Total savings: 71.11%
- Duration: 0.24 seconds
Sample Debug Output (Multi-Configuration Alloy):
Processing configuration: cards
Processing android from: originals
Processing iphone from: originals
Processing configuration: thumbs
Processing android from: thumbs
Processing iphone from: thumbs
Processed files:
- app/assets/android/images/res-mdpi/cards/baby/card1.webp (config: cards, platform: android, scale: res-mdpi)
- app/assets/android/images/res-hdpi/cards/baby/card1.webp (config: cards, platform: android, scale: res-hdpi)
- app/assets/iphone/images/cards/baby/card1.webp (config: cards, platform: iphone, scale: 1x)
- app/assets/iphone/images/cards/baby/card1@2x.webp (config: cards, platform: iphone, scale: 2x)
- app/assets/android/images/res-mdpi/thumbs/baby/thumb1.webp (config: thumbs, platform: android, scale: res-mdpi)
...
Processing complete! Summary:
- Processed files: 24
- Total original size: 2.45 MB
- Total new size: 0.89 MB
- Total savings: 63.67%
- Duration: 1.24 seconds
This information can be useful for troubleshooting and optimizing the image processing workflow.
Q: Why did my .jpg file become .jpeg in older versions?
A: This was an issue in versions prior to 1.1.4. Update to the latest version where original extensions are preserved when no format conversion is specified.
Q: The CLI says "format not supported" for my file
A: Ensure your file has one of these extensions: .jpeg, .jpg, .png, .webp, .avif, .tiff, .gif
Q: Batch processing failed on some files
A: Check file permissions and ensure the output directory is writable. Use --debug flag for detailed error information.
Q: Output quality seems poor
A: Adjust quality with -q parameter (1-100). Default is 85. Use -q 95 for higher quality.
Q: Permission denied error
A: Run with sudo on macOS/Linux: sudo imgconvert ... or check file/directory permissions.
Q: Sharp installation fails A: Install build tools:
# On macOS
xcode-select --install
# On Ubuntu/Debian
sudo apt-get install build-essential
# On Windows
npm install -g windows-build-tools
# Alternative: install node-gyp globally
npm install -g node-gyp
Q: Out of memory on large batches A: Process in smaller batches or increase Node.js memory:
node --max-old-space-size=4096 $(which imgconvert) large-folder
Q: Images appear blurry or pixelated A: Ensure source images are high enough resolution. For Alloy preset, use 4x resolution source images for best results.
Q: Alloy preset not generating expected output structure
A: Verify your configuration file format and ensure output paths don't include leading/trailing slashes (use "thumbs/baby" not "/thumbs/baby/")
We welcome contributions! Here's how you can help improve imgconvert-cli:
Fork the repository
# On GitHub, click the "Fork" button
Clone your fork
git clone https://github.com/yourusername/imgconvert-cli.git
cd imgconvert-cli
Install dependencies
npm install
Run tests
npm test
Create your feature branch
git checkout -b feature/amazing-feature
Make your changes and test
# Make your changes
npm test
npm run lint
Commit your changes
git commit -m 'Add amazing feature'
Push to your branch
git push origin feature/amazing-feature
Open a Pull Request
base: main ← compare: your-feature-branchAfter Creating the PR
git checkout main
git pull upstream main
git checkout feature/amazing-feature
git merge main
## What does this PR do?
Brief description of the changes
## Why is this needed?
Explain the problem this solves
## How to test?
Steps to verify the changes work
## Checklist:
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No breaking changes (or clearly documented)
💡 Have an idea? Open an issue to discuss new features or improvements!
This project is licensed under the MIT License.
Copyright (c) 2025 César Estrada
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Made with ❤️ by César Estrada
FAQs
A CLI tool for compressing and converting images
The npm package imgconvert-cli receives a total of 55 weekly downloads. As such, imgconvert-cli popularity was classified as not popular.
We found that imgconvert-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.
Security News
/Research
Widespread GitHub phishing campaign uses fake Visual Studio Code security alerts in Discussions to trick developers into visiting malicious website.