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.1.10 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
-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.1.10
--check / --no-check: source, cache, output, and manifest freshness assertion for CI in version 0.1.10
--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.

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