CLI, without
the guesswork.
Every flag, default, and behavior. Start with a preset, then override only what you need.
Install
Node.js 22.5 or newer. The only runtime dependency is sharp.
npm install --save-dev pixelpress # or run it without installing npx pixelpress --help
Quick start
# One image, three widths
pixelpress hero.jpg -o dist -w 480,960,1920
# A whole tree, keeping structure
pixelpress public/images -o dist/images -r
# Glob input and a preset
pixelpress "assets/**/*.{jpg,png}" -o dist -r --preset web
# Pipe one image through stdout
cat photo.jpg | pixelpress - -f webp --stdout > photo.webp
Output mirrors the input tree. With --widths, the width is appended: hero-480.avif, hero-960.avif. Widths larger than the source are skipped unless --enlarge is set.
Presets
Presets are starting points. Any explicit flag overrides them — formats, widths, quality, fit, and so on.
| Preset | Formats | Size | Defaults |
|---|---|---|---|
web | AVIF, WebP | widths 480, 960, 1920 | AVIF 50, WebP 72 |
thumb | WebP | width 400 | WebP 72 |
social | JPEG, WebP | 1200 × 630 cover | JPEG 82, WebP 78 |
lossless | PNG, WebP | original size | lossless, PNG palette off |
pixelpress products -o dist -r --preset web pixelpress og.jpg -o social --preset social pixelpress icons -o dist -r --preset lossless # Preset + override: keep qualities, replace widths pixelpress products -o dist -r --preset web --widths 640,1280
Input & bulk
| Option | Default | Behavior |
|---|---|---|
<file|dir|glob...> | required | Files, directories, or quoted globs. Node expands globs, not the shell. |
-r, --recursive | off | Include subdirectories of directory inputs. |
--include <glob> | all | Only process matching files. Repeatable. |
--exclude <glob> | none | Skip matching files. Repeatable. |
--follow-symlinks | off | Follow symlinked files and directories. |
-c, --config <file> | auto | JSON or ESM config. Auto-loads pixelpress.config.json. |
Include/exclude patterns match both the path relative to the input root and the basename, so --include "*.jpg" catches nested JPEGs. With multiple directory/glob roots, outputs are prefixed by each root's basename; --flat drops the tree.
pixelpress "assets/**/*.{jpg,png}" -o dist -r \
--include "products/**" --exclude "*-draft.*"
pixelpress images -o dist -r --follow-symlinks
pixelpress a b -o dist # out/a/... and out/b/...
Output & naming
| Option | Default | Behavior |
|---|---|---|
-o, --out <dir> | pixelpress-out | Output directory. Refuses to equal an input directory. |
-f, --formats <list> | avif,webp | Any of avif,webp,jpeg,png (or jpg). |
--preset <name> | none | web, thumb, social, lossless. |
-w, --widths <list> | source size | Responsive widths. Never upscales unless --enlarge. |
--width <px> | none | Single resize width; not with --widths. |
--height <px> | none | Single resize height; not with --widths. |
--fit <mode> | inside | cover, contain, fill, inside, outside. |
--position <pos> | center | Crop gravity, e.g. attention, entropy, right top. |
--enlarge | off | Allow upscaling. |
--prefix <text> | none | Prepend to output filenames. |
--suffix <text> | none | Append to output filenames. |
--hash | off | Append an 8-character SHA-256 content hash. |
--flat | off | Flatten output. Collisions are errors. |
--clean | off | Delete output directory first; guarded against inputs/root/home/cwd. |
--preserve-dates | off | Copy source timestamps onto outputs. |
Name order is <prefix><name><suffix>[-<width>][-<hash>].<ext>. Prefix and suffix cannot contain path separators.
pre-hero-2x-960-a1b2c3d4.avif pre-hero-2x-1920-a1b2c3d4.avif pre-hero-2x-960-a1b2c3d4.webp
Transforms
| Option | Behavior |
|---|---|
--rotate <deg> | Rotate by degrees. Overrides EXIF auto-orientation. |
--no-auto-orient | Ignore EXIF orientation (on by default). |
--flip, --flop | Flip vertically / horizontally. |
--grayscale | Convert to grayscale. |
--blur <sigma> | Gaussian blur. |
--sharpen <sigma> | Sharpen; 1 is a good starting point. |
--normalize | Stretch contrast across the full range. |
--gamma <value> | Gamma correction. |
--tint <color> | Tint while preserving luminance. |
--trim <threshold> | Trim uniform borders, 1–100. |
--extract <WxH+X+Y> | Crop a region, e.g. 800x600+100+50. |
--extend <edges> | Pad: 10, 10,20, or 10,20,30,40 (top,right,bottom,left). |
--density <dpi> | Rasterization density for SVG input. |
Encoding
| Option | Default | Behavior |
|---|---|---|
-q, --quality <value> | per format | 1–100, or avif=50,webp=72. |
--effort <value> | avif 4, webp 4, png 10 | CPU effort, or avif=6,webp=4,png=10. |
--lossless | off | Lossless AVIF/WebP/PNG. JPEG is rejected. |
--progressive / --no-progressive | on | Progressive or baseline JPEG. |
--chroma-subsampling <s> | 4:2:0 | 4:2:0, 4:2:2, 4:4:4. |
--alpha-quality <n> | 100 | WebP alpha quality. |
--palette / --no-palette | auto | Force or disable PNG quantization. |
--compression-level <n> | 9 | PNG zlib level 0–9. |
--max-bytes <size> | none | Lower quality per variant until it fits, e.g. 150kb. |
--background <color> | #ffffff | Matte for transparent JPEGs, rotation, extend. |
--keep-metadata | off | Keep EXIF/ICC instead of stripping. |
Default quality is AVIF 55, WebP 78, JPEG 80, PNG 80. PNG quantizes to a palette below quality 100; use --quality png=100 or --lossless. --max-bytes is per variant. If even quality 1 cannot fit, the file fails.
Workflow
| Option | Default | Behavior |
|---|---|---|
--manifest <file> | none | JSON report with variants, dimensions, bytes, quality, frames, cache state, and srcset. |
--picture <file> | none | <picture> snippets for every input. |
--report <file> | none | Self-contained before/after HTML report. |
--public-path <path> | / | URL prefix for picture snippets. |
--sizes <value> | 100vw | sizes attribute for snippets. |
--lqip | off | Tiny WebP data URI placeholder + dominant color. |
--cache / --no-cache | on | Reuse cached outputs; disable per run. |
--cache-dir <dir> | node_modules/.cache/pixelpress | Cache location. One hashed file per output dir. |
--prune | off | Delete cached outputs no longer produced. Requires cache. |
--force | off | Re-encode even when cached. |
--fail-fast | off | Stop after the first failed file. |
--concurrency <n> | 4 | Files processed in parallel. |
--dry-run | off | Plan without writing images or reports. |
--stdout | off | Write one encoded image to stdout. |
--json | off | Print the full report as JSON. |
--quiet / --verbose | off | Summary only / list every variant. |
--watch | off | Re-run when inputs change. |
--init | off | Create a starter config and exit. |
Stream mode accepts exactly one input and one format. Use --width/--height, not --widths. It cannot combine with --out (other than -), --watch, --clean, --dry-run, --json, --manifest, --picture, or --report. Logs go to stderr.
Cache, prune, watch
The CLI caches by default. Cache files live outside deployable output at node_modules/.cache/pixelpress/cache-<hash>.json. Fingerprints cover formats, widths, transforms, quality, metadata, and paths. The PIXELPRESS_CACHE_DIR environment variable sets the default.
pixelpress photos -o dist -r # first run pixelpress photos -o dist -r # cached pixelpress photos -o dist -r --force # re-encode pixelpress photos -o dist -r --prune # clean retired outputs pixelpress photos -o dist -r --cache-dir .cache pixelpress photos -o dist -r --watch
--prune only deletes regular files recorded in the cache and inside --out. It never deletes inputs, failed-file outputs, or fail-fast leftovers, and it removes empty directories. A dry run does not delete. Cache writes are atomic and best-effort; a read-only cache directory never fails an image run.
--watch uses recursive fs.watch where the platform supports it. Elsewhere it watches every directory and refreshes the watcher set as subdirectories appear or disappear. Editing pixelpress.config.json reloads it without restarting the watcher; a broken config is reported and the previous runtime keeps running.
--force when in doubt.Config & schema
Create a starter config:
pixelpress --init # writes pixelpress.config.json with the web preset, inputs, outDir, # cache, prune, and a $schema reference
{
"$schema": "./node_modules/pixelpress/pixelpress.schema.json",
"preset": "web",
"inputs": ["src/images/**/*.{jpg,png}"],
"outDir": "public/images",
"recursive": true,
"cache": true,
"prune": true,
"manifest": "public/images.json",
"report": "public/report.html"
}
Auto-detected in the current directory. Use --config other.json for another path. .mjs and .js configs with a default export work too. CLI flags override config values. Paths resolve from the current working directory.
The schema is published at node_modules/pixelpress/pixelpress.schema.json for editor completion and validation.
Environment & exit codes
| Name | Effect |
|---|---|
PIXELPRESS_CACHE_DIR | Default cache directory when --cache-dir is absent. |
NO_COLOR | Disable ANSI color in terminal output. |
The CLI exits 0 on success, 1 when any file or prune operation fails, or when no supported inputs are found. --json still prints the report on partial failure, so CI can archive it.
Next: Node API · Recipes · Comparison