img-convert

img-convert

Sharp-based image converter. This guide covers v2 of the CLI (img-convert --version prints 2.x). Prefer the CLI; the MCP server and Node API are covered briefly at the end.

Rules for agents

1. Always pass --json and parse stdout. Progress and warnings go to stderr.
2. Parse stdout even when the exit code is 1. Exit 1 means some items failed; the JSON array still lists every item. Check each item's ok.
3. Exit 2 means the command itself was wrong (bad flag, unknown format, no matching files, bad manifest). With --json, stdout is {"error":{"code","message"}}. Fix the command; don't retry it unchanged.
4. Read the output path from the JSON. Don't predict it: filenames are sanitized (my photo.jpg → my_photo.webp).
5. Quote glob patterns ("imgs/*.png", "imgs/**/*.png" where ** recurses into subfolders, "*.{jpg,png}") so the CLI expands them, not the shell. Prefer absolute paths.
6. Run img-convert info first on images you know nothing about (alpha, animation, size).
7. For different settings per file, use a batch manifest (img-convert batch - --json reads it from stdin) instead of a shell loop.
8. No in-place edits: writing to the input's own path is refused (OUTPUT_IS_INPUT). Write to another directory with -o, then move the file if needed.
9. Metadata (including GPS) is kept by default. Pass --no-metadata to strip it.

Recipes

# Convert one file (output goes next to the input: photo.webp)
img-convert /abs/photo.jpg -f webp --json

# Web-optimize a folder into another folder
img-convert "/abs/site/img/*.{jpg,png}" -f webp -q 80 --no-metadata -o /abs/site/img-webp --json

# Exact-size square thumbnail (crops to fill)
img-convert /abs/photo.jpg -f webp --width 200 --height 200 --fit cover -o /abs/thumbs --json

# Fit inside a box, keep aspect ratio (default --fit inside; never enlarges)
img-convert /abs/banner.png -f jpeg --width 1280 --height 720 --json

# Stay under an upload limit (highest quality that fits; jpeg/webp/avif only)
img-convert /abs/photo.png -f jpeg --max-size 200KB --json

# Strip EXIF/GPS but keep the format: write elsewhere, then move.
# This re-encodes the image, so use a high -q to avoid visible quality loss.
img-convert /abs/photo.jpg -f jpeg -q 95 --no-metadata -o /abs/clean --json && mv /abs/clean/photo.jpg /abs/photo.jpg

# iPhone HEIC → JPEG (HEIC must be a local .heic/.heif file or stdin)
img-convert /abs/IMG_0001.HEIC -f jpeg --json

# Transparent PNG → JPEG (transparency becomes white; choose another fill with --background)
img-convert /abs/logo.png -f jpeg --background "#000000" --json

# Crop a region (left,top,width,height in pixels of the upright source), then resize
img-convert /abs/shot.png -f png --crop 100,50,800,600 --width 400 -o /abs/out --json

# Keep animation (GIF/WebP → GIF/WebP only)
img-convert /abs/anim.gif -f webp --json

# From a URL (saved in the current directory unless -o is given)
img-convert https://example.com/pic.png -f avif -o /abs/downloads --json

# Pipe: stdin → stdout (no JSON; errors on stderr, exit 1)
cat in.png | img-convert -f webp > out.webp

# Inspect a folder
img-convert info "/abs/imgs/*"

# Whole tree, recursively (quote the glob)
img-convert "/abs/imgs/**/*.png" -f webp -o /abs/out --json

# Same filenames in different folders (a/x.png, b/x.png) would collide in one -o dir
# (DUPLICATE_OUTPUT). Keep them apart by giving each item its own outputDir:
find /abs/imgs -name '*.png' | jq -R '{input: ., format: "webp", outputDir: ("/abs/out" + (. | ltrimstr("/abs/imgs") | sub("/[^/]*$"; "")))}' \
  | jq -s . | img-convert batch - --json

# Preview a big job without writing anything
img-convert "/abs/imgs/**/*.png" -f avif -o /abs/out --dry-run --json

# Different settings per file
echo '[{"input":"/abs/a.png","format":"webp","width":800},{"input":"/abs/b.png","format":"jpeg","maxSize":"100KB"}]' \
  | img-convert batch - --json