CLI Reference | Pulp Image

Installation

Pulp Image CLI requires Node.js 18 or higher. Install globally via npm to make the pulp command available anywhere:

Install globally

$ npm install -g pulp-image

Verify installation

$ pulp --version
0.0.0

Basic Usage

The basic syntax for Pulp is:

Command syntax

pulp [input] [options]

# input: A file path or directory path
# options: Various flags to control processing

Quick Examples

pulp image.png --format webp: Convert to WebP
pulp image.png --width 800: Resize to 800px wide
pulp ./images --format avif --out ./output: Batch convert a folder

All Options

Option	Description	Default
`-w, --width <number>`	Output width in pixels. Aspect ratio is preserved if height is not specified.	-
`-h, --height <number>`	Output height in pixels. Aspect ratio is preserved if width is not specified.	-
`-f, --format <format>`	Output format: `png`, `jpg`, `webp`, or `avif`	Same as input
`-o, --out <dir>`	Output directory. Created automatically if it doesn't exist.	`./pulp-image-results`
`--quality <number>`	Quality for lossy formats (1-100). Higher = better quality, larger file.	JPG: 80, WebP: 80, AVIF: 50
`--lossless`	Use lossless compression for WebP and AVIF. PNG is always lossless.	Off (lossy)
`--suffix <text>`	Custom suffix added before file extension. E.g., "optimized" → `image-optimized.png`	-
`--auto-suffix`	Automatically add size-based suffix: `-800w`, `-600h`, or `-800x600`	Off
`--background <color>`	Background color (hex) for transparency flattening when converting to JPG.	`#ffffff`
`--alpha-mode <mode>`	How to handle transparency: `flatten` (composite onto background) or `error` (fail if present)	`flatten`
`--overwrite`	Overwrite existing output files. By default, existing files are skipped.	Off (skip)
`--delete-original`	Delete original files after successful processing. Only works if input/output paths differ.	Off
`-v, --verbose`	Show detailed per-file processing information.	Off
`--version`	Display version number.	-
`--help`	Display help information.	-

Resize Images

Resize images by specifying width, height, or both. When only one dimension is provided, aspect ratio is automatically preserved.

Resize by width (preserves aspect ratio)

$ pulp photo.png --width 800

✓ Processed: pulp-image-results/photo.png
  Original: 4.2 MB (3000x2000)
  Final:    892 KB
  Saved:    3.32 MB (79%)

Resize by height (preserves aspect ratio)

$ pulp photo.png --height 600

Resize to exact dimensions

$ pulp photo.png --width 800 --height 600

# Output will be exactly 800x600, cropping if needed

Resize with auto-suffix (adds size to filename)

$ pulp photo.png --width 800 --auto-suffix

# Output: photo-800w.png

Format Conversion

Convert between PNG, JPG, WebP, and AVIF formats. Each format has different characteristics:

Format	Transparency	Compression	Default Quality
`png`	✓ Yes	Always lossless	-
`jpg`	✗ No	Always lossy	80
`webp`	✓ Yes	Lossy or lossless	80
`avif`	✓ Yes	Lossy or lossless	50

Convert PNG to WebP (preserves transparency)

$ pulp image.png --format webp

Convert to JPG with custom background color

$ pulp image.png --format jpg --background "#ff6b35"

# Transparent areas become orange (#ff6b35)

Convert to AVIF with custom quality

$ pulp photo.jpg --format avif --quality 70

# Quality 70 = good balance of size and quality

Lossless WebP conversion

$ pulp image.png --format webp --lossless

# No quality loss, still smaller than PNG

High-quality JPG for photography

$ pulp photo.png --format jpg --quality 95

# Quality 95 = near-lossless, still good compression

Batch Processing

Process entire directories of images at once. Pulp will find all supported image files (PNG, JPG, WebP, AVIF) in the directory.

Convert all images in a folder to WebP

$ pulp ./images --format webp --out ./output

Found 12 image file(s) to process...

✓ Processed: 12 file(s)
  Total original size: 48.2 MB
  Total final size:    8.4 MB
  Total saved:         39.8 MB (82.57%)

Batch resize with auto-suffix

$ pulp ./images --width 800 --auto-suffix --out ./thumbnails

# Each file gets a -800w suffix: photo-800w.png

Batch process with verbose output

$ pulp ./images --format webp --out ./output --verbose

# Shows detailed info for each file processed

Batch process with combined suffix

$ pulp ./images --width 800 --auto-suffix --suffix "thumb" --format webp

# Output: photo-800w-thumb.webp

Safety Features

Pulp is designed to protect your files. By default, nothing is overwritten or deleted.

Default Behavior (Safe)

Output goes to ./pulp-image-results (never overwrites originals)
Existing files in output directory are skipped
Original files are never deleted
Processing continues even if individual files fail

Enable overwriting existing output files

$ pulp ./images --format webp --out ./output --overwrite

# Replaces existing files in ./output

Delete originals after processing (use with caution!)

$ pulp ./images --format webp --out ./output --delete-original

# ⚠️ Original files are deleted after successful processing
# Only works when output path differs from input path

⚠️ Warning

The --delete-original flag permanently removes source files. Only use this when you're certain the processed output is correct and you no longer need the originals.

Transparency Handling

When converting to formats that don't support transparency (like JPG), Pulp can either flatten the transparency onto a background color or fail with an error.

Flatten to white background (default)

$ pulp logo.png --format jpg

# Transparent areas become white (#ffffff)

Flatten to custom color

$ pulp logo.png --format jpg --background "#1a1b26"

# Transparent areas become dark blue (#1a1b26)

Fail if image has transparency

$ pulp logo.png --format jpg --alpha-mode error

# Exits with error if transparency is detected

Real-World Examples

Web Optimization Workflow

Create optimized WebP versions for web

$ pulp ./assets --format webp --quality 85 --out ./public/images

# Great for web deployment - modern format with transparency

Generate Responsive Image Sizes

Create multiple sizes for responsive images

# Run multiple times with different widths:
$ pulp ./photos --width 400 --auto-suffix --format webp --out ./responsive
$ pulp ./photos --width 800 --auto-suffix --format webp --out ./responsive
$ pulp ./photos --width 1200 --auto-suffix --format webp --out ./responsive

# Creates: photo-400w.webp, photo-800w.webp, photo-1200w.webp

Social Media Images

Optimize for social sharing (flatten transparency)

$ pulp cover.png --format jpg --quality 90 \
    --width 1200 --height 630 \
    --background "#ffffff"

# Perfect dimensions for Open Graph/Twitter cards

CI/CD Pipeline

Optimize images during build

# In your CI/CD script or package.json:
$ pulp ./src/images --format webp --quality 80 \
    --out ./dist/images --overwrite

# Overwrites on each build for fresh output

Archive Compression

Maximum compression for archival

$ pulp ./archive --format avif --quality 40 --out ./compressed

# AVIF at quality 40 = excellent compression with acceptable quality

Browser UI Mode

Pulp includes a browser-based interface for those who prefer a visual approach:

Start the browser UI

$ pulp ui

Starting Pulp Image UI...
Server running at http://localhost:3000
Press Ctrl+C to stop

Start on a custom port

$ pulp ui --port 8080

Starting Pulp Image UI...
Server running at http://localhost:8080

ℹ️ Note

The browser UI provides the same features as the CLI but with a visual interface. Processing happens locally on your machine. No files are uploaded to the internet.

Troubleshooting

Common Errors

"Input not found"

The specified file or directory doesn't exist. Check the path is correct and the file exists.

"Output file already exists"

Use --overwrite to replace existing files, or use a different output directory.

"Image contains transparency"

When converting to JPG with --alpha-mode error, this means the source has transparency. Either use --alpha-mode flatten with a --background color, or choose a format that supports transparency (PNG, WebP, AVIF).

"Cannot delete original: same as output"

The --delete-original flag only works when the output path differs from the input path. Use --out to specify a different output directory.