CLI reference

The complete reference for the imgsqz command.

Synopsis

imgsqz <input...> [options]

• <input...> — required. One or more image file paths. Globs are expanded by your shell. imgsqz reads any format sharp supports (JPG, PNG, WebP, AVIF, TIFF, GIF, SVG, and more).

Options

Flag	Argument	Default	Description
-f, --format	<format>	jpg	Output format: jpg, jpeg, png, webp, avif, tiff. jpeg → jpg.
-q, --quality	<1-100>	80	Compression quality. Lower = smaller file. Integer 1–100.
-o, --output	<path>	—	Exact output path. Single input only. Creates missing directories.
--width	<px>	—	Resize width in pixels (positive integer).
--height	<px>	—	Resize height in pixels (positive integer).
--fit	<mode>	inside	Fit when width and height are set: cover, contain, fill, inside, outside.
--enlarge	—	off	Allow upscaling beyond the source dimensions.
--lossless	—	off	Lossless mode (WebP / AVIF / PNG).
--grayscale	—	off	Convert to grayscale.
--no-strip-metadata	—	strip	Preserve EXIF / ICC metadata (stripped by default).
--no-timestamp	—	on	Omit the _<timestamp> suffix from auto-named output.
--replace	—	off	Overwrite the source file in place (atomic).
--quiet	—	off	Suppress per-file progress output. Errors still print.
-v, --version	—	—	Print the version and exit.
-h, --help	—	—	Show help and exit.

About the --no-* flags

--no-strip-metadata and --no-timestamp are negations of behaviors that are on by default. There are no --strip-metadata / --timestamp flags — the default already does those, and the --no- form turns them off.

Flag details

-f, --format <format>

Sets the output encoder. Accepts jpg, jpeg, png, webp, avif, tiff. jpeg is normalized to jpg. An unsupported value is rejected with a clear error. See Format behavior for per-format encoder settings.

-q, --quality <1-100>

Integer quality from 1 to 100. Out-of-range or non-integer values are rejected. Interpreted per format; ignored for true fidelity in --lossless mode (output is exact). Default 80.

-o, --output <path>

An exact destination path. The extension in the path is cosmetic — the encoding comes from -f. Parent directories are created automatically. Cannot be combined with multiple inputs.

--width <px> / --height <px>

Target dimensions in pixels (positive integers). Provide one to scale proportionally, or both with --fit to control how the image fills the box. Applied after EXIF auto-rotation. See Resizing & fit modes.

--fit <mode>

Only relevant when both --width and --height are set:

• inside (default) — fit within the box, preserve aspect ratio, no crop.
• outside — cover the box, preserve aspect ratio, no crop.
• cover — fill the box exactly, cropping overflow.
• contain — fit within the box, padding the remainder.
• fill — stretch to the exact box, ignoring aspect ratio.

--enlarge

By default imgsqz won’t upscale past the source’s native size. --enlarge removes that guard.

--lossless

Enables lossless encoding for webp, avif, and png. For PNG it also disables palette quantization, preserving full color depth.

--grayscale

Drops color, producing a grayscale image. Reduces file size for content that doesn’t need color.

--no-strip-metadata

Keeps EXIF and ICC metadata. By default they’re stripped for smaller files and privacy. Orientation is corrected regardless (see Metadata & orientation).

--no-timestamp

Removes the _<timestamp> suffix from auto-generated output names, giving clean names like photo.webp. Ignored when you pass -o or --replace.

--replace

Overwrites the source in place using an atomic temp-file-and-rename. See Replacing files in place.

--quiet

Suppresses the per-file success report. Failures and the non-zero exit code are unaffected.

Exit codes

Code	Meaning
0	All inputs processed successfully.
1	At least one input failed, or a usage error (e.g. -o with multiple inputs, bad flag value).

See Exit codes & errors for the full list of error messages.

Output report format

For each successful file (unless --quiet):

<absolute input path>
  → <absolute output path>
  <input size> → <output size> (<↓|↑> <percent>%)

↓ means the output is smaller; ↑ means larger. Sizes are human-readable (B / KB / MB / GB).

--help output

Usage: imgsqz [options] <input...>

Compress and convert images. Default: write an optimized JPG next to the
source with a _<timestamp>.jpg suffix.

Arguments:
  input                 one or more image file paths

Options:
  -v, --version         output the version number
  -f, --format <format> output format (choices: "jpg", "jpeg", "png",
                        "webp", "avif", "tiff", default: "jpg")
  -q, --quality <n>     quality 1-100 (lower = smaller file) (default: 80)
  -o, --output <path>   explicit output path (only valid with a single input)
  --width <px>          resize width in pixels
  --height <px>         resize height in pixels
  --fit <mode>          resize fit mode when both width and height are set
                        (choices: "cover", "contain", "fill", "inside",
                        "outside", default: "inside")
  --enlarge             allow upscaling beyond the source dimensions
  --lossless            lossless mode (webp/avif/png)
  --grayscale           convert to grayscale
  --no-strip-metadata   preserve EXIF / ICC metadata (stripped by default)
  --no-timestamp        omit the _<timestamp> suffix
  --replace             overwrite the source file in place
  --quiet               suppress per-file progress output
  -h, --help            display help for command