webimg-cli

A fast and simple Node.js CLI to batch optimize images and videos for the web. Compress, resize, and convert to modern formats like WebP, AVIF, and WebM in a single command.

Built for photographers and developers who need to quickly turn high-resolution exports into lightweight, web-ready files.

Features

• Batch processing -- process entire folders of images or videos at once
• Image optimization -- compress and convert PNG, JPEG, WebP, and AVIF with sharp
• Video optimization -- convert MP4 to optimized MP4 + WebM with ffmpeg (bundled)
• Smart resizing -- resize to max width/height while preserving aspect ratio, never upscales
• Metadata stripping -- removes EXIF and other unnecessary data
• Progress bar -- real-time progress with ETA for large batches
• Concurrent processing -- processes multiple images in parallel for speed
• Zero config ffmpeg -- ffmpeg and ffprobe are bundled, no system install needed

Installation

npm install -g webimg-cli

Or use directly with npx (no install required):

npx webimg-cli --images -i ./photos -o ./web -f webp -w 2000

Usage

The CLI has two modes: --images for image files and --video for video files.

Images

Convert and optimize image files. Requires --format to specify the output format.

# Convert all images to WebP, max 2000px wide
webimg-cli --images -i ./photos -o ./web -f webp -w 2000

# Convert to AVIF with custom quality
webimg-cli --images -i ./raw -o ./optimized -f avif -q 50

# Resize to fit within 1920x1080, output as JPEG
webimg-cli --images -i ./input -o ./output -f jpeg -w 1920 --height 1080

Supported input formats: PNG, JPEG/JPG, WebP, AVIF

Supported output formats: PNG, JPEG, WebP, AVIF

Videos

Optimize video files. Each input MP4 produces two output files: an optimized MP4 and a WebM version. No --format flag needed.

# Optimize all MP4 videos, scale down to 1920px wide
webimg-cli --video -i ./videos -o ./web -w 1920

# Optimize without resizing
webimg-cli --video -i ./videos -o ./web

Input: MP4

Output: Optimized MP4 (H.264 + AAC) and WebM (VP9 + Opus)

Options

| Flag | Alias | Description | Required | |------|-------|-------------|----------| | --images | | Process image files | One of --images or --video | | --video | | Process video files | One of --images or --video | | --input | -i | Input directory | Yes | | --output | -o | Output directory (created if missing) | Yes | | --format | -f | Output image format: png, jpeg, webp, avif | Only with --images | | --width | -w | Max width in pixels | No | | --height | | Max height in pixels | No | | --quality | -q | Quality level (images: 1-100, video: CRF) | No | | --concurrency | | Parallel workers (default: 4) | No |

Default quality settings

Images

| Format | Quality | Notes | |--------|---------|-------| | JPEG | 80 | Uses mozjpeg for smaller files | | WebP | 80 | Good balance of quality and size | | AVIF | 60 | AVIF compresses more efficiently at lower values | | PNG | Level 9 | Maximum compression with palette optimization |

Videos

| Format | Codec | Audio | CRF | Notes | |--------|-------|-------|-----|-------| | MP4 | H.264 | AAC 128k | 23 | movflags +faststart for web streaming | | WebM | VP9 | Opus 128k | 30 | Excellent compression for modern browsers |

Example workflow

project/
  photos/
    hero.png         (8.2 MB)
    portrait.jpg     (5.1 MB)
    landscape.png    (12.4 MB)

  videos/
    promo.mp4        (48 MB)

webimg-cli --images -i ./photos -o ./web -f webp -w 2000
webimg-cli --video -i ./videos -o ./web -w 1920

web/
  hero.webp          (180 KB)
  portrait.webp      (120 KB)
  landscape.webp     (240 KB)
  promo.mp4          (12 MB)
  promo.webm         (9 MB)

Requirements

• Node.js >= 18

Development

git clone https://github.com/tadeuszderuijter/webimg-cli.git
cd webimg-cli
npm install
npm run build
npm run start -- --images -i ./photos -o ./web -f webp -w 2000

License

Apache-2.0