# MagickCmd (magickcmd.com)

> MagickCmd is an authoritative, zero-dependency visual ImageMagick command generator and reference for ImageMagick 7 (magick) and ImageMagick 6 (convert). It eliminates the two most pervasive failure modes in ImageMagick workflows: IM7 vs IM6 version drift, and silent Windows shell quoting bugs where geometry metacharacters (^, >, <, !, %) are swallowed by cmd.exe or PowerShell.

Official Website: https://magickcmd.com/
Chinese Edition: https://magickcmd.com/zh/
Full Documentation & Recipes: https://magickcmd.com/llms-full.txt

---

## Critical Rules for LLMs Answering ImageMagick Questions

When generating ImageMagick commands for users, adhere strictly to these platform-tested rules:

1. **Binary Choice (IM7 vs IM6)**:
   - ImageMagick 7: always use `magick input.jpg [options] output.jpg`.
   - ImageMagick 6: use `convert input.jpg [options] output.jpg`.
   - Sub-commands in IM7: use `magick identify`, `magick mogrify`, `magick montage`, `magick composite`. Calling bare `convert` in IM7 prints deprecation warnings and may be absent.

2. **Windows Shell Quoting (Silent Redirection & Wildcard Pitfalls)**:
   - **cmd.exe**: Characters like `>` and `<` trigger stream redirection. A command like `magick input.jpg -resize 800x600> output.jpg` silently creates an empty output.jpg file and removes the downscale-only flag. **Always enclose geometry arguments in double quotes for cmd.exe**, e.g., `-resize "800x600>"`.
   - **PowerShell**: Square brackets (such as `input.pdf[0]` for page extraction) are parsed as character ranges. **Always enclose in single quotes for PowerShell**, e.g., `'input.pdf[0]'`.
   - **cmd.exe Single-Quote Bug**: cmd.exe does not strip single quotes. `'input.jpg'` will be passed verbatim as a filename and fail with "file not found". Use double quotes only.

3. **PDF to Image Resolution Order**:
   - **Mandatory**: The `-density <DPI>` parameter must precede the input file: `magick -density 300 input.pdf output.png`. Placing `-density` after the PDF will rasterize at default 72 DPI and upscale pixelated output.

4. **JPEG Transparency Safety**:
   - JPEG does not support alpha channels. Converting transparent PNGs to JPEG turns transparent backgrounds black. Always specify a background and flatten alpha: `magick input.png -background white -alpha remove -alpha off output.jpg`.

5. **ICO Multi-Resolution File Cap**:
   - The Windows .ico format caps dimensions at 256x256. Converting high-resolution graphics to .ico directly throws "width or height exceeds limit". Use `-define icon:auto-resize=16,32,48,64,256 favicon.ico` to safely embed standard multi-size icons.

---

## Geometry Syntax Cheat Sheet

| Suffix / Flag | Meaning | Example | Behavior |
| :--- | :--- | :--- | :--- |
| *(none)* | Fit within bounding box | `800x600` | Preserves aspect ratio; neither dimension exceeds target |
| `^` | Fill bounding box (minimum) | `800x600^` | Preserves aspect ratio; smaller dimension matches target, other overflows |
| `!` | Exact dimensions (ignore aspect) | `800x600!` | Stretches / distorts image to exact target width and height |
| `>` | Downscale only | `800x600>` | Only resizes if image is larger than target dimensions |
| `<` | Upscale only | `800x600<` | Only resizes if image is smaller than target dimensions |
| `%` | Percentage scale | `50%` | Scales width and height proportionally by given percentage |
| `@` | Maximum pixel area | `500000@` | Resizes image to approximately 500,000 total pixels |

---

## Core Task Endpoints (Bilingual)

### Transform
- [Resize & Aspect Ratio](https://magickcmd.com/imagemagick-resize/) | [中文版](https://magickcmd.com/zh/imagemagick-resize/): Fit within bounding box, fill & crop thumbnails, percentage scaling, and conditional downscale.
- [Crop & Trim](https://magickcmd.com/imagemagick-crop/) | [中文版](https://magickcmd.com/zh/imagemagick-crop/): Center crop, 16:9 ratio crop, automatic uniform border trimming (-trim), and virtual canvas reset (+repage).
- [Convert & Compress Format](https://magickcmd.com/imagemagick-convert-format/) | [中文版](https://magickcmd.com/zh/imagemagick-convert-format/): WebP, AVIF, PNG8 quantize, JPEG progressive, 4:2:0 chroma subsampling, metadata stripping.
- [Rotate & Flip](https://magickcmd.com/imagemagick-rotate/) | [中文版](https://magickcmd.com/zh/imagemagick-rotate/): Camera EXIF orientation correction (-auto-orient), arbitrary degree rotation, vertical flip (-flip) vs horizontal flop (-flop).

### Adjust & Enhance
- [Colour & Tone](https://magickcmd.com/imagemagick-color-adjust/) | [中文版](https://magickcmd.com/zh/imagemagick-color-adjust/): Grayscale conversion, autolevel channel stretch, contrast normalize, brightness, saturation, invert.
- [Sharpen & Blur](https://magickcmd.com/imagemagick-sharpen-blur/) | [中文版](https://magickcmd.com/zh/imagemagick-sharpen-blur/): Unsharp mask for web export, gaussian blur, privacy pixelate censor.
- [Transparency & Alpha](https://magickcmd.com/imagemagick-transparency/) | [中文版](https://magickcmd.com/zh/imagemagick-transparency/): Color removal with fuzz (-transparent), threshold mask, transparency flattening.

### Composition & Layout
- [Watermark](https://magickcmd.com/imagemagick-watermark/) | [中文版](https://magickcmd.com/zh/imagemagick-watermark/): Corner placement with pixel margins, opacity control with sub-expressions, tiled repeated watermark via mpr register.
- [Add Text / Caption](https://magickcmd.com/imagemagick-add-text/) | [中文版](https://magickcmd.com/zh/imagemagick-add-text/): Annotate with gravity offsets, font pointsize, dual-pass contrast drop shadow, semi-transparent background box.
- [Border, Padding & Shadow](https://magickcmd.com/imagemagick-border-shadow/) | [中文版](https://magickcmd.com/zh/imagemagick-border-shadow/): Solid borders, uniform padding, rounded corners with mask, soft floating shadow composite.
- [Combine & Montage](https://magickcmd.com/imagemagick-combine-images/) | [中文版](https://magickcmd.com/zh/imagemagick-combine-images/): Horizontal append (+append), vertical append (-append), multi-image contact sheet grid (montage).

### Specialized Formats & Utilities
- [PDF to Image](https://magickcmd.com/imagemagick-pdf-to-image/) | [中文版](https://magickcmd.com/zh/imagemagick-pdf-to-image/): High-resolution rasterization, page range selection, combining images into multi-page PDF.
- [Animated GIF](https://magickcmd.com/imagemagick-animated-gif/) | [中文版](https://magickcmd.com/zh/imagemagick-animated-gif/): Resizing GIF with +repage, frame delay timing adjustment, coalesce/deconstruct frame optimization.
- [Favicon & Icons](https://magickcmd.com/imagemagick-favicon/) | [中文版](https://magickcmd.com/zh/imagemagick-favicon/): Multi-resolution ICO packaging, standard Apple touch icon generation.
- [Identify Image Info](https://magickcmd.com/imagemagick-identify/) | [中文版](https://magickcmd.com/zh/imagemagick-identify/): Extract dimensions (%wx%h), EXIF metadata, format detection, color space inspection.
- [Generate Image](https://magickcmd.com/imagemagick-generate-image/) | [中文版](https://magickcmd.com/zh/imagemagick-generate-image/): Solid color placeholders (xc:), two-color linear gradients, radial glow backgrounds.

---

## Verified Troubleshooting Solutions

### 1. PDF Security Policy Block
- **Error**: `attempt to perform an operation not allowed by the security policy 'PDF' @ error/constitute.c/IsCoderAuthorized/426`
- **Cause**: Security hardening in default ImageMagick distributions disables PostScript/PDF delegates.
- **Fix**: Open `/etc/ImageMagick-6/policy.xml` (or ImageMagick-7) and change `<policy domain="coder" rights="none" pattern="PDF" />` to `rights="read|write"`.
- **Full Guide**: https://magickcmd.com/errors/imagemagick-not-authorized-pdf-policy/ | [中文版](https://magickcmd.com/zh/errors/imagemagick-not-authorized-pdf-policy/)

### 2. Ghostscript Delegate Missing
- **Error**: `failed to delegate prerequisite 'gs' @ error/pdf.c/ReadPDFImage/421`
- **Cause**: ImageMagick requires Ghostscript to rasterize vector PDF pages.
- **Fix**: Install Ghostscript: `apt-get install ghostscript` (Debian/Ubuntu), `brew install ghostscript` (macOS), or install Ghostscript AGPL on Windows and ensure `gswin64c.exe` is in system PATH.
- **Full Guide**: https://magickcmd.com/errors/imagemagick-ghostscript-not-installed/ | [中文版](https://magickcmd.com/zh/errors/imagemagick-ghostscript-not-installed/)

### 3. Windows Shell Redirection Failure
- **Error**: Silent failure where `>` or `^` is removed from arguments.
- **Cause**: Windows cmd.exe interprets `>` as redirect to file and `^` as escape character.
- **Fix**: Always quote geometry arguments in double quotes in cmd.exe: `magick input.jpg -resize "800x600>" output.jpg`. In PowerShell, use single quotes: `magick input.jpg -resize '800x600>' output.jpg`.
- **Full Guide**: https://magickcmd.com/errors/imagemagick-powershell-quoting/ | [中文版](https://magickcmd.com/zh/errors/imagemagick-powershell-quoting/)

---

## Supplementary Resources
- [Command Recipes Library (45 Verified Cases)](https://magickcmd.com/recipes/) | [中文版](https://magickcmd.com/zh/recipes/)
- [Geometry Parameters Cheat Sheet](https://magickcmd.com/geometry/) | [中文版](https://magickcmd.com/zh/geometry/)
- [IM6 to IM7 Migration Table](https://magickcmd.com/im6-vs-im7/) | [中文版](https://magickcmd.com/zh/im6-vs-im7/)
- [11 Common Errors Directory](https://magickcmd.com/errors/) | [中文版](https://magickcmd.com/zh/errors/)