Skip to main content
ImageForge is sunset. The site and npm package remain available; no new feature work is planned.
Browse documentation

CLI reference

ImageForge CLI command reference

Choose and reproduce the options that define your generated image contract.

Commands and exit status

Run imageforge against a directory containing supported source images. Normal generation exits 1 if a file fails. Check mode exits 1 when processing is needed and 0 when the checked source, cache, and derivative state is current.

imageforge <directory> [options]
imageforge init [--force]
imageforge --help
imageforge --version

Published defaults

Version 0.2.0 defaults to a root imageforge.json manifest, WebP at quality 80, blur placeholders with sample size 4, cache enabled, and derivatives next to their sources. Concurrency defaults to the smaller of 8 and the available parallelism. Responsive widths and a separate output directory are opt-in.

Generation options

  • -f, --formats <formats>: webp, avif, or both; unsupported values exit with an error before processing
  • -q, --quality <number>: output quality from 1 to 100
  • --widths <list>: up to 16 source-bounded responsive widths
  • --blur / --no-blur: enable or disable blurDataURL generation
  • --out-dir <path>: place derivatives in a separate directory
  • -o, --output <path>: set the manifest path
  • --blur-size <number>: blur sample dimension from 1 to 256; default 4
  • --concurrency <number>: bounded parallel work from 1 to 64

Workflow options

  • --dry-run / --no-dry-run: filesystem-pure preview without derivative, manifest, cache, output-directory, or lock writes in version 0.2.0
  • --check / --no-check: source, cache, output, and manifest freshness assertion for CI in version 0.2.0
  • --json: machine-readable report on stdout
  • --include / --exclude: repeatable input-relative glob filters
  • --concurrency <number>: bounded parallel work from 1 to 64
  • --config <path>: select an explicit JSON config
  • --cache / --no-cache: enable or disable the persistent cache
  • --force-overwrite: allow no-cache runs to replace owned outputs
  • --verbose / --no-verbose: enable or disable detailed output
  • --quiet / --no-quiet: enable or disable non-error output
  • -V, --version: print the installed CLI version
  • -h, --help: print command help

Guardrails and incompatibilities

Check and dry-run modes cannot be combined. Width lists allow at most 16 unique positive targets and never upscale beyond source dimensions. Discovery skips symlinks, output collision checks are case-insensitive, and existing conflicting outputs are protected unless overwrite is explicitly authorized.

Include and exclude globs are input-relative. Keep generation and check options identical; changing formats, quality, widths, filters, output path, or output directory changes the generated-state contract.

Upgrading to v0.2.0 invalidates existing cache entries because Sharp and libvips changed. Regenerate and review derivatives, manifest, and cache before running --check.

Initialize configuration

imageforge init creates imageforge.config.json and refuses to replace an existing file. Review the existing file or pass --force intentionally.

imageforge init
imageforge init --force