MicroPng CLI

A high-performance, local-first CLI image compressor built with Node.js and libvips (via sharp). Designed for developers who need fast, reliable, and recursive image optimization without sending data to a cloud service.

🚀 Features

• Blazing Fast: Uses parallel processing with smart concurrency control to saturate your CPU without crashing.
• Deeply Recursive: Scans folders and subfolders, maintaining your directory structure perfectly.
• Safety First: Implements atomic overwrites using the --replace flag—original files are only replaced if the compressed version is actually smaller.
• Universal Formats: Full support for JPEG, PNG, WebP, and AVIF conversion and compression.
• Local-First: No data ever leaves your machine. Your privacy is guaranteed.
• Smarter Scanning: Native support for ignore patterns to skip node_modules, .git, or specific assets.
• Metadata Control: Choose whether to strip or keep EXIF information (GPS, camera settings, etc.).

📦 Installation

Global Installation

Install it once and use the micropng-cli command anywhere:

npm install -g micropng-cli

Run without Installation

Use npx to run it instantly without cluttering your system:

npx micropng-cli --help

🛠 Usage Examples

1. Basic Compression

Compress a single file and save it as a new file:

micropng-cli input.png --output optimized.png

2. High-Performance Bulk Processing

Optimize an entire directory and maintain the structure in an output folder:

micropng-cli ./raw-assets --output ./dist/assets --recursive

3. Safe In-Place Replacement

The most popular way to use MicroPng. This will search through your project and optimize all images, replacing them only if size is saved:

micropng-cli ./src --recursive --replace --quality 85

4. Advanced: Modern Web Formats

Convert all images in a folder to WebP for modern web performance:

micropng-cli ./images --format webp --output ./webp-bundle --recursive

5. Advanced: Complex Ignores

Ignore specific directories or patterns while processing:

micropng-cli . --recursive --replace --ignore "node_modules/**" "**/previews/**" "*.tmp"

⚙️ Options

| Option | Alias | Description | Default | | :--- | :--- | :--- | :--- | | --output <dir> | -o | Target directory for compressed files; for a single file input, can be an output file path (e.g. optimized.png) | (Current Dir) | | --recursive | -r | Deep scan folders and subfolders | false | | --replace | | Replace originals (Atomic safety enabled) | false | | --quality <n> | -q | Compression quality (1-100) | 80 | | --format <type> | -f | Output format (jpeg, png, webp, avif) | (Source Ext) | | --concurrency <n> | -c | Max simultaneous tasks | 5 | | --ignore <glob> | -i | Patterns to exclude (supports multiple) | - | | --keep-metadata| | Preserves EXIF/GPS/IPTC data | false |

📖 Additional Docs

• Changelog: See what's new in each version.
• Contributing: Learn how to set up the dev environment and add new features.
• Distribution: Details on the build and release pipeline.

⚖️ License

MIT © Sahil Fruitwala