compress
Compress to a target file size, searching quality (and optionally dimensions) for the best result that fits.
Compress one or more images to a target size — the flagship command, and the only one where
--to is required.
compress <inputs...> --to <size> [--format keep|jpeg|png|webp] [--no-downscale] [--max-encodes N]Flags
| Flag | Required | Meaning |
|---|---|---|
--to <size> |
yes | target size: 50kb, 500k, 1mb, or a bare byte count like 51200. 1024-based — 50kb is 51,200 bytes. |
--format keep|jpeg|png|webp |
no | output format. Default keep (the source’s own format; HEIC sources resolve to jpeg, since HEIC is decode-only). |
--no-downscale |
no | don’t reduce pixel dimensions to hit the target — only encoder quality moves. Without it, downscaling is allowed by default. |
--max-encodes N |
no | cap on encode attempts (a positive integer). The search stops and reports BUDGET_EXHAUSTED rather than running indefinitely. |
--format accepts keep, jpeg, png or webp — not heic (decode-only, never a valid output)
and not avif (this command’s own flag validation rejects it; avif is a real ImageFormat the
engine understands, just not one compress/resize/crop/rotate --format will take from you).
Examples
Compress to under 50 KB, writing photo-compressed.jpg next to the source:
imagekbreducer compress photo.jpg --to 50kbCompress a batch to WebP, into a build output directory, pinning dimensions (no downscale) and capping the search:
imagekbreducer compress src/*.jpg --to 80kb --format webp --no-downscale --max-encodes 8 --out dist/imgWhat can go wrong
| Exit | When |
|---|---|
| 2 | --to missing or not a parseable size; --format/--max-encodes invalid |
| 3 | an input doesn’t exist, or a glob matched nothing |
| 4 | the computed output already exists and isn’t the input (pass --force, --out, or --suffix) |
| 10 | target-unreachable / FIXED_DIMENSIONS — the quality floor is still over target with --no-downscale set; drop it |
| 11 | target-unreachable / MIN_DIMENSION — downscaling was allowed but the next step would go below the minimum dimension |
| 12 | target-unreachable / FORMAT_FLOOR — out of downscale room; try --format webp |
| 13 | target-unreachable / BUDGET_EXHAUSTED — ran out of encode attempts; raise --max-encodes, or pass --accept-closest |
| 20 | unsupported-format — not a jpeg/png/webp/heic source (renamed SVG, GIF, BMP, …) |
| 21 | decode-failed — truncated or corrupt bytes |
| 22 | input-too-large |
| 23 | dimension-exceeded |
| 24 | encode-failed |
10–13 are all target-unreachable: not a crash, a negotiation. The stderr sentence and the
--json suggestions array both name the flag that would actually help — see
Exit codes for the full table and --json output for the
machine-readable shape. --accept-closest turns any of the four into exit 0, writing the closest
file the search found instead of failing.