Imagemagick CLI

ImageMagick CLI

Use ImageMagick 7 to build, run, and verify reproducible image-processing commands. Keep the main workflow short; load the bundled reference that matches the requested operation.

Workflow

1. Resolve magick and run magick -version. Use scripts/resolve-imagemagick.ps1 on Windows or scripts/resolve-imagemagick.sh on Linux/macOS when discovery is uncertain. If ImageMagick cannot be found, tell the user to download and install it from https://imagemagick.org/download.
2. Inspect the input with magick identify -ping or magick identify -verbose when metadata, alpha, profiles, pages, or frames matter.
3. Read the relevant reference below, construct an ImageMagick 7 command for the user’s shell, and preserve originals unless in-place editing is explicit.
4. Run the command when requested, check the exit code, then verify the output with identify, compare, and visual inspection as appropriate.

Core rules

• Use ImageMagick 7 syntax: magick input [operators] output and subcommands such as magick identify, magick mogrify, magick montage, magick compare, and magick stream.
• Respect sequential evaluation. Put read settings such as -density, raw -size, and decoder -define values before the input they affect.
• Quote all paths and shell-sensitive geometry. Use parentheses to isolate operations on overlays, masks, clones, or other nested image lists.
• Treat magick mogrify as destructive unless -path writes to a separate directory.
• Run -auto-orient before geometry-sensitive work on camera images.
• Use +repage after crop or trim when later operations should ignore the old virtual canvas.
• Manage alpha, colorspace, profiles, animation timing, and multi-page scenes deliberately; do not silently discard them.
• Confirm optional formats, fonts, delegates, policies, compose methods, and kernels with the installed magick -list ... commands.
• For untrusted or very large inputs, use format allowlists and limits for area, memory, map, disk, time, and threads.
• Verify outputs instead of relying on file existence alone.

Shell forms

PowerShell:

$magick = (Get-Command magick -ErrorAction Stop).Source
& $magick "input image.png" -auto-orient -resize "1600x1600>" "output image.jpg"

Pass parentheses as literal arguments:

& $magick "background.png" "(" "overlay.png" -resize "25%" ")" `
  -gravity southeast -geometry "+24+24" -compose over -composite "result.png"

Bash/zsh:

magick "input image.png" -auto-orient -resize '1600x1600>' "output image.jpg"
magick background.png \( overlay.png -resize 25% \) \
  -gravity southeast -geometry +24+24 -compose over -composite result.png

Prefer PowerShell over cmd.exe for complex Windows commands. In cmd batch files, use ^ for continuation and double % characters.

Command references

• references/cli-foundations.md — evaluation order, settings and operators, stacks, geometry grammar, pseudo-images, streams, shell quoting, and IM6-to-IM7 conversion.
• references/inspect-formats-metadata.md — identify, percent escapes, EXIF/profiles, format prefixes, multi-image I/O, common and specialist coders, delegates, encrypted images, raw data, and large streams.
• references/geometry-resize-crop.md — fit/fill/exact resize, thumbnails, resampling filters, density, orientation, crop/page/extent, advanced trim, borders, tiling, and framing.
• references/color-tone-quantize.md — colorspaces, ICC, channels, alpha, grayscale, levels, histogram operations, thresholds, palettes, and dithering.
• references/compose-mask-layers.md — compose operators, placement, opacity, alpha/read/write masks, background removal, chroma key, hole filling, regions, clones, layers, watermarks, and shadows.
• references/draw-text-canvas.md — canvases, gradients, patterns, fonts, label/caption/annotate, Pango, form filling, gravity, symbols, MVG, paths, and text effects.
• references/filters-effects-morphology.md — blur, sharpen, denoise, convolution, edge/Hough detection, morphology kernels and pattern matching, deskew, CLAHE, shade, and photographic effects.
• references/distort-map-fx.md — affine/SRT, perspective, lens correction, control points, virtual pixels, displacement/absolute/variable-blur maps, -evaluate, -function, -fx, and sparse color.
• references/animation-montage-compare.md — frame metadata, coalesce/disposal, animation edits/merging/optimization, video palettes/deinterlacing, contact sheets, metrics, diffs, and subimage search.
• references/batch-performance-security.md — safe PowerShell/Bash batching, mogrify, naming, resource limits, concurrency, policies, temporary files, and failure logs.
• references/advanced-analysis.md — histograms, pixel enumeration, connected components, convex hull, classification heuristics, kernels, FFT/HDRI, raw streaming, and calculated options.
• references/photo-thumbnail-effects.md — digital-photo cleanup, selective focus/anonymization, multiple exposures, green screen, sketch/vignette work, thumbnail decoration, reflections, and constructed lighting effects.
• references/options-index.md — on-demand alphabetized CLI option signatures. Search for the exact option; do not read the index end to end.
• references/defines-index.md — on-demand -define keys grouped by coder or operation. Search for the coder/prefix or exact key; do not read the index end to end.

For large indexes, search before reading the entire file:

options-index.md:  ^### -resize\b
defines-index.md:  png:|jpeg:|compare:|connected-components:

Verification patterns

magick identify -format '%f|%m|%wx%h|%z-bit|%[colorspace]|%[channels]|%n\n' output.png
magick identify -format '%s|%T|%D|%wx%h|%[page]\n' animation.gif
magick compare -metric RMSE expected.png actual.png null:

Comparison metrics commonly write to stderr, and a nonzero compare status can mean that images differ. Capture the metric and diagnostic text separately in automation.

Response style

• State assumptions that affect pixels, cropping, transparency, metadata, colorspace, or animation behavior.
• Give commands for the user’s actual shell.
• Explain only the non-obvious ordering or operators.
• Warn before destructive mogrify use.
• Include verification for batch, lossy, animated, color-managed, multi-page, or security-sensitive work.