PicMorphCLI is a fast, interactive command-line interface tool built with Bun for resizing, compressing, and converting images (either single images or entire directories).
This guide covers everything you need to know to install, use, and contribute to PicMorphCLI.
- Format Conversion: Convert images between
webp,png,jpeg/jpg, andavifformats. - Bulk Processing: Process a single image file or batch-convert all images within an entire directory.
- Image Resizing: Resize images by specifying a custom width and height, supporting various fit options (
fill,inside). - Advanced Optimization Options:
- WebP Lossless conversion toggle.
- Custom PNG compression levels (0-9).
- Progressive JPEG output toggle.
- Image quality adjustments (1-100).
- Auto-output: Dynamically saves all processed images to your user home
Pictures/pic-morph/directory, creating it automatically if it does not exist.
You need Bun installed on your system. If you don't have it yet, install it via:
curl -fsSL https://bun.sh/install | bashTo install pic-morph globally as a CLI command on your system:
bun install -g @wanderleedev/pic-morphnpm install -g @wanderleedev/pic-morphOnce installed globally, you can launch the interactive editor from any terminal. It is designed to be fully interactive, meaning you just start the tool and follow the prompts!
pic-morph(If you are developing locally, run bun run index.ts instead)
The tool will ask you for a path:
? Enter the path to the image or image directory:
You can provide either:
- A path to a single image (e.g.,
./photo.jpgor/home/user/Downloads/image.png) - A path to a directory (e.g.,
./images/or/home/user/Pictures/raw/). The tool will automatically find and process all supported images inside that directory.
? Select the output format:
❯ webp
png
jpeg
avif
jpg
Use your arrow keys to select the desired format and press Enter. (Note: If your system does not have the necessary codecs for AVIF, it will automatically be disabled and greyed out to prevent errors).
Depending on the format you chose, PicMorphCLI will ask specific optimization questions:
- WebP: Ask if conversion should be lossless.
- PNG: Ask for compression level (0-9).
- JPEG/JPG: Ask to enable progressive conversion.
- All: Ask for the desired image quality (1-100).
You will be prompted for width and height. You can press Enter to skip resizing, or type a number. If you choose to resize, you can also select the fit mode:
fill: Stretch the image to perfectly fill the given dimensions.inside: Keep the image's original aspect ratio while ensuring it fits within the given dimensions.
PicMorphCLI will process your files and automatically save them in your system's pictures directory:
~/Pictures/pic-morph/Want to run the code locally or contribute to the project?
- Clone the repository:
git clone https://github.com/WanderleeDev/pic-morph-cli.git cd pic-morph-cli - Install dependencies:
bun install
- Run the CLI locally:
bun run index.ts
To run the unit tests, use the built-in test runner:
bun run testThis project uses release-it to manage package versioning, Git commits/tags, and publishing. To release a new version, run:
bun run releaseFollow the interactive prompts to bump the version (patch, minor, or major) and automatically create the corresponding Git tags and commits.
If you see an error like:
❌ Error: El formato de imagen (avif) no está soportado en esta máquina.
This happens because Bun's native image processor delegates encoding/decoding of modern formats (like AVIF or HEIC) to system-level libraries. You can resolve this by installing the required codecs:
- Debian/Ubuntu Linux:
sudo apt-get update sudo apt-get install -y libavif-dev libheif-dev
- macOS (via Homebrew):
brew install shared-mime-info libavif libheif
- Runtime: Bun
- Language: TypeScript
- Interactive Prompts: Inquirer.js