@blazediff/cli

CLI for image comparison. Wraps the native Rust binary (fastest), JS pixel diff, GMSD, SSIM, MS-SSIM, and Hitchhiker’s SSIM.

View Detailed Benchmarks

Installation

Global Installation


npm install -g @blazediff/cli


pnpm add -g @blazediff/cli


yarn global add @blazediff/cli


bun add --global @blazediff/cli

Local Installation


npm install --save-dev @blazediff/cli


pnpm add --save-dev @blazediff/cli


yarn add --dev @blazediff/cli


bun add --dev @blazediff/cli

Using npx


npx blazediff-cli image1.png image2.png -o diff.png


pnpm dlx blazediff-cli image1.png image2.png -o diff.png


yarn dlx blazediff-cli image1.png image2.png -o diff.png


bun x blazediff-cli image1.png image2.png -o diff.png

Available Commands

core-native (default)

`blazediff-cli core-native` (default)

Native Rust binary with SIMD optimization. The fastest option - 3-4x faster than odiff on large images.

Basic Usage


# Default command (core-native)
blazediff-cli image1.png image2.png -o diff.png
 
# Or explicitly
blazediff-cli core-native image1.png image2.png -o diff.png

With Options


blazediff-cli image1.png image2.png -o diff.png --threshold 0.05 --no-antialiasing

Options

core-native, core and core-wasm take the same flags as the Rust blazediff CLI. Anti-aliased pixels are detected and left out of the count unless you pass --no-antialiasing.


blazediff-cli core-native <image1> <image2> [options]
 
Options:
  -o, --output <path>       Output path for the diff image
  -t, --threshold <num>     Matching threshold (0 to 1, default: 0.1)
  --no-antialiasing         Count anti-aliased pixels as differences
  --metric <name>           Color metric: yiq (default) or oklab (pixelmatch 8)
  --mask <path>             Image whose non-black pixels are skipped
  --window <n>              Also report the n×n window with the most differences
  -a, --alpha <num>         Opacity of the original image in the diff (default: 0.1)
  --diff-color <r,g,b>      Color for different pixels (default: 255,0,0)
  --diff-color-alt <r,g,b>  Color for pixels that get darker (default: diff color)
  --aa-color <r,g,b>        Color for anti-aliased pixels (default: 255,255,0)
  --background <name>       faded (default) or transparent
  --json                    Print the result as JSON
  --compression <num>       PNG compression level (0-9, default: 0)
  --quality <num>           JPEG quality (1-100, default: 90)
  -h, --help                Show this help message

--json prints the result object, for example {"kind":"compared","count":121,"percentage":0.09,"identical":false}.

Exit Codes

0 - Images are identical
1 - Images differ, or their dimensions do not match
2 - Error (file not found, invalid format, etc.)


blazediff-cli image1.png image2.png -o diff.png
if [ $? -eq 0 ]; then
  echo "Images match!"
else
  echo "Images differ!"
fi

Why so fast? Uses a two-pass block-based algorithm with SIMD acceleration (NEON on ARM, SSE4.1 on x86). The cold pass quickly identifies unchanged blocks, then the hot pass only processes changed regions.

interpret

`blazediff-cli interpret`

Describes what changed rather than only where: region detection, content-aware classification (Addition, Deletion, Shift, ContentChange, ColorChange, RenderingNoise), severity scoring and a human-readable summary.

Basic Usage


blazediff-cli interpret <image1> <image2> [output] [options]
 
Options:
  --source <name>           How to locate regions: pixel (default), ssim,
                            ms-ssim, hitchhikers-ssim
  -t, --threshold <num>     Color difference threshold (0-1, default: 0.1). pixel only
  -a, --antialiasing        Exclude anti-aliased pixels. pixel only
  -c, --compression <num>   PNG compression level (0-9, default: 0)
  --window-size <num>       Local window size for the metric sources (default: 11)
  --region-floor <num>      Window score at or below which it counts as changed (default: 0.99)
  --regions <json>          Skip the search and classify these boxes instead
  --json                    Print the full result as JSON
  -h, --help                Display help

output is written by the pixel source only — the metric sources and --regions have no diff visualization to write.

Example


$ blazediff-cli interpret image1.png image2.png --json
{
  "summary": "Moderate visual change detected (1.87% of image, 4 regions).\n...",
  "severity": "Medium",
  "diffPercentage": 1.87,
  "regions": [...]
}

Exit Codes

0 - Nothing actionable changed
1 - Change detected
2 - Error

core

`blazediff-cli core`

Pure JavaScript pixel-by-pixel comparison. Slower than core-native, with no native dependencies. core-wasm takes the same flags.

Basic Usage


blazediff-cli core image1.png image2.png

Save Diff Image


blazediff-cli core image1.png image2.png --output diff.png

Options


blazediff-cli core <image1> <image2> [options]
 
Options:
  -o, --output <path>       Output path for the diff image
  -t, --threshold <num>     Matching threshold (0 to 1, default: 0.1)
  --no-antialiasing         Count anti-aliased pixels as differences
  --metric <name>           Color metric: yiq (default) or oklab (pixelmatch 8)
  --mask <path>             Image whose non-black pixels are skipped
  --window <n>              Also report the n×n window with the most differences
  -a, --alpha <num>         Opacity of the original image in the diff (default: 0.1)
  --diff-color <r,g,b>      Color for different pixels (default: 255,0,0)
  --diff-color-alt <r,g,b>  Color for pixels that get darker (default: diff color)
  --aa-color <r,g,b>        Color for anti-aliased pixels (default: 255,255,0)
  --background <name>       faded (default) or transparent
  --json                    Print the result as JSON
  --codec <name>            Codec to use (pngjs, sharp, jsquash-png)
  -h, --help                Show this help message

Exit Codes

0 - Images are identical or within threshold
1 - Images differ beyond threshold, or their dimensions do not match
2 - Error


blazediff-cli core image1.png image2.png
if [ $? -eq 0 ]; then
  echo "Images match!"
else
  echo "Images differ!"
fi

gmsd

`blazediff-cli gmsd`

GMSD (Gradient Magnitude Similarity Deviation) perceptual quality assessment. Returns a similarity score from 0-1.

Basic Usage


blazediff-cli gmsd image1.png image2.png

Save GMS Map


blazediff-cli gmsd image1.png image2.png --output gms-map.png

Options


blazediff-cli gmsd <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output GMS map image path
  --downsample <n>         Downsample factor (0 or 1, default: 0)
  -h, --help              Display help

Output

Prints the GMSD score (lower = more similar):

0.0 - Images are identical
0.0-0.05 - Very low difference
0.05-0.15 - Low difference
0.15-0.35 - Moderate difference
>0.35 - High difference

Example


$ blazediff-cli gmsd reference.png test.png
GMSD: 0.0234
 
$ blazediff-cli gmsd reference.png test.png --output gms-map.png
GMSD: 0.0234
GMS map saved to: gms-map.png

ssim

`blazediff-cli ssim`

Standard SSIM (Structural Similarity Index) with Gaussian weighting. MATLAB-compatible with <0.01% error.

Basic Usage


blazediff-cli ssim image1.png image2.png

Save SSIM Map


blazediff-cli ssim image1.png image2.png --output ssim-map.png

Options


blazediff-cli ssim <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output SSIM map image path
  --window-size <n>        Gaussian window size (default: 11)
  --k1 <n>                 Algorithm parameter (default: 0.01)
  --k2 <n>                 Algorithm parameter (default: 0.03)
  -h, --help              Display help

Output

Prints the SSIM score (higher = more similar):

1.0 - Identical images
0.99+ - Excellent similarity
0.95-0.99 - Very good similarity
0.90-0.95 - Good similarity
0.80-0.90 - Fair similarity
<0.80 - Poor similarity

Example


$ blazediff-cli ssim reference.png test.png
SSIM: 0.9876
 
$ blazediff-cli ssim reference.png test.png --output ssim-map.png --window-size 8
SSIM: 0.9823
SSIM map saved to: ssim-map.png

msssim

`blazediff-cli msssim`

MS-SSIM (Multi-Scale SSIM) for better perceptual correlation. Analyzes images at multiple scales.

Basic Usage


blazediff-cli msssim image1.png image2.png

Save MS-SSIM Map


blazediff-cli msssim image1.png image2.png --output msssim-map.png

Options


blazediff-cli msssim <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output SSIM map at finest scale
  --window-size <n>        Gaussian window size (default: 11)
  --scales <n>             Number of scales (default: 5)
  --method <type>          Aggregation method: product or sum (default: product)
  -h, --help              Display help

Prints the MS-SSIM score (higher = more similar, same scale as SSIM).


$ blazediff-cli msssim reference.png test.png
MS-SSIM: 0.9912

hitchhikers-ssim

`blazediff-cli hitchhikers-ssim`

Hitchhiker’s SSIM - fast rectangular-window SSIM using integral images. ~4x faster than standard SSIM.

Basic Usage


blazediff-cli hitchhikers-ssim image1.png image2.png

Save SSIM Map


blazediff-cli hitchhikers-ssim image1.png image2.png --output ssim-map.png

Options


blazediff-cli hitchhikers-ssim <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output SSIM map image path
  --window-size <n>        Rectangular window size (default: 11)
  --window-stride <n>      Window stride (default: window-size)
  --no-cov-pooling         Disable CoV pooling (use mean pooling)
  --k1 <n>                 Algorithm parameter (default: 0.01)
  --k2 <n>                 Algorithm parameter (default: 0.03)
  -h, --help              Display help

Prints the SSIM score (higher = more similar, same scale as SSIM). CoV pooling is enabled by default.


$ blazediff-cli hitchhikers-ssim reference.png test.png
SSIM: 0.9597

When to Use Each Algorithm

Algorithm	Best for
`core-native` (default)	Maximum speed, CI/CD, large images
`core`	No native dependencies, runs anywhere Node runs
`gmsd`	Similarity score, compression-tolerant
`ssim`	MATLAB-compatible, research
`msssim`	Multi-scale, varying resolutions
`hitchhikers-ssim`	Fast SSIM (~4x), large batches

@blazediff/cli

Installation

Global Installation

Local Installation

Using npx

Available Commands

core-native (default)

blazediff-cli core-native (default)

Basic Usage

With Options

Options

Exit Codes

interpret

blazediff-cli interpret

Basic Usage

Example

Exit Codes

core

blazediff-cli core

Basic Usage

Save Diff Image

Options

Exit Codes

gmsd

blazediff-cli gmsd

Basic Usage

Save GMS Map

Options

Output

Example

ssim

blazediff-cli ssim

Basic Usage

Save SSIM Map

Options

Output

Example

msssim

blazediff-cli msssim

Basic Usage

Save MS-SSIM Map

Options

hitchhikers-ssim

blazediff-cli hitchhikers-ssim

Basic Usage

Save SSIM Map

Options

When to Use Each Algorithm

Links

`blazediff-cli core-native` (default)

`blazediff-cli interpret`

`blazediff-cli core`

`blazediff-cli gmsd`

`blazediff-cli ssim`

`blazediff-cli msssim`

`blazediff-cli hitchhikers-ssim`