Reference

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.

shell
npm install --save-dev pixelpress
# or run it without installing
npx pixelpress --help
Use the CLI in a project or on a build box. The API is the same engine; see Node API.

Quick start

shell
# 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.

PresetFormatsSizeDefaults
webAVIF, WebPwidths 480, 960, 1920AVIF 50, WebP 72
thumbWebPwidth 400WebP 72
socialJPEG, WebP1200 × 630 coverJPEG 82, WebP 78
losslessPNG, WebPoriginal sizelossless, PNG palette off
shell
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

OptionDefaultBehavior
<file|dir|glob...>requiredFiles, directories, or quoted globs. Node expands globs, not the shell.
-r, --recursiveoffInclude subdirectories of directory inputs.
--include <glob>allOnly process matching files. Repeatable.
--exclude <glob>noneSkip matching files. Repeatable.
--follow-symlinksoffFollow symlinked files and directories.
-c, --config <file>autoJSON 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.

shell
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

OptionDefaultBehavior
-o, --out <dir>pixelpress-outOutput directory. Refuses to equal an input directory.
-f, --formats <list>avif,webpAny of avif,webp,jpeg,png (or jpg).
--preset <name>noneweb, thumb, social, lossless.
-w, --widths <list>source sizeResponsive widths. Never upscales unless --enlarge.
--width <px>noneSingle resize width; not with --widths.
--height <px>noneSingle resize height; not with --widths.
--fit <mode>insidecover, contain, fill, inside, outside.
--position <pos>centerCrop gravity, e.g. attention, entropy, right top.
--enlargeoffAllow upscaling.
--prefix <text>nonePrepend to output filenames.
--suffix <text>noneAppend to output filenames.
--hashoffAppend an 8-character SHA-256 content hash.
--flatoffFlatten output. Collisions are errors.
--cleanoffDelete output directory first; guarded against inputs/root/home/cwd.
--preserve-datesoffCopy source timestamps onto outputs.

Name order is <prefix><name><suffix>[-<width>][-<hash>].<ext>. Prefix and suffix cannot contain path separators.

example output
pre-hero-2x-960-a1b2c3d4.avif
pre-hero-2x-1920-a1b2c3d4.avif
pre-hero-2x-960-a1b2c3d4.webp

Transforms

OptionBehavior
--rotate <deg>Rotate by degrees. Overrides EXIF auto-orientation.
--no-auto-orientIgnore EXIF orientation (on by default).
--flip, --flopFlip vertically / horizontally.
--grayscaleConvert to grayscale.
--blur <sigma>Gaussian blur.
--sharpen <sigma>Sharpen; 1 is a good starting point.
--normalizeStretch 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

OptionDefaultBehavior
-q, --quality <value>per format1–100, or avif=50,webp=72.
--effort <value>avif 4, webp 4, png 10CPU effort, or avif=6,webp=4,png=10.
--losslessoffLossless AVIF/WebP/PNG. JPEG is rejected.
--progressive / --no-progressiveonProgressive or baseline JPEG.
--chroma-subsampling <s>4:2:04:2:0, 4:2:2, 4:4:4.
--alpha-quality <n>100WebP alpha quality.
--palette / --no-paletteautoForce or disable PNG quantization.
--compression-level <n>9PNG zlib level 0–9.
--max-bytes <size>noneLower quality per variant until it fits, e.g. 150kb.
--background <color>#ffffffMatte for transparent JPEGs, rotation, extend.
--keep-metadataoffKeep 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

OptionDefaultBehavior
--manifest <file>noneJSON report with variants, dimensions, bytes, quality, frames, cache state, and srcset.
--picture <file>none<picture> snippets for every input.
--report <file>noneSelf-contained before/after HTML report.
--public-path <path>/URL prefix for picture snippets.
--sizes <value>100vwsizes attribute for snippets.
--lqipoffTiny WebP data URI placeholder + dominant color.
--cache / --no-cacheonReuse cached outputs; disable per run.
--cache-dir <dir>node_modules/.cache/pixelpressCache location. One hashed file per output dir.
--pruneoffDelete cached outputs no longer produced. Requires cache.
--forceoffRe-encode even when cached.
--fail-fastoffStop after the first failed file.
--concurrency <n>4Files processed in parallel.
--dry-runoffPlan without writing images or reports.
--stdoutoffWrite one encoded image to stdout.
--jsonoffPrint the full report as JSON.
--quiet / --verboseoffSummary only / list every variant.
--watchoffRe-run when inputs change.
--initoffCreate 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.

shell
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.

Cache invalidation uses mtime + size. Replacing a file while keeping both identical is treated as unchanged. Use --force when in doubt.

Config & schema

Create a starter config:

shell
pixelpress --init
# writes pixelpress.config.json with the web preset, inputs, outDir,
# cache, prune, and a $schema reference
pixelpress.config.json
{
  "$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

NameEffect
PIXELPRESS_CACHE_DIRDefault cache directory when --cache-dir is absent.
NO_COLORDisable 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