@compare-ui/cli

Command-line tools for design-comparison workflows.

This package provides:

• comparison runs for a reference image and an actual image
• artifact-only render runs
• utility commands for grid, overlay, join, and crop

Installation

pnpm add -D @compare-ui/cli @compare-ui/core

The CLI is intended to be installed in the consuming workspace as a development tool.

Commands

Main workflow commands:

• design compare
• design render

Utility commands:

• design grid
• design overlay
• design join
• design crop

Shared config

The CLI can read design-comparison.config.mts.

Example:

design compare ^
  --reference ./figma.png ^
  --actual ./actual.png ^
  --config ./design-comparison.config.mts

design compare

design compare runs the comparison step and then writes the configured artifacts and report.

Important options:

--reference
--actual
--config
--name
--output-folder
--min-similarity-percent
--max-diff-percent
--reference-crop-top
--reference-crop-right
--reference-crop-bottom
--reference-crop-left
--actual-crop-top
--actual-crop-right
--actual-crop-bottom
--actual-crop-left
--json

Example:

design compare ^
  --reference ./figma-screen.png ^
  --actual ./actual.png ^
  --name home-screen ^
  --output-folder ./design-tests ^
  --max-diff-percent 0.5 ^
  --reference-crop-bottom 20

The CLI accepts both:

• --max-diff-percent
• --min-similarity-percent

so existing workflows can use either threshold style from the command line.

design render

design render skips comparison and generates only the configured artifacts.

This is useful when you want:

• overlays
• grid images
• joined review sheets

without calculating diff metrics.

Example:

design render ^
  --reference ./figma-screen.png ^
  --actual ./actual.png ^
  --config ./design-comparison.config.mts

design grid

Adds a grid to one image.

Example:

design grid ^
  --input ./image.png ^
  --output ./image-grid.png ^
  --size 16 ^
  --offset-x 0 ^
  --offset-y 0 ^
  --color 0,153,255 ^
  --alpha 0.28 ^
  --line-width 2

design overlay

Creates one overlay image from a reference image and an actual image.

Example:

design overlay ^
  --reference ./figma.png ^
  --actual ./actual.png ^
  --output ./overlay.png ^
  --overlay-alpha 0.5

design join

Joins multiple images into one output image.

Example:

design join ./reference-grid.png ./actual-grid.png ^
  --output ./joined.png ^
  --direction horizontal ^
  --gap 12

design crop

Crops one image by edge offsets.

Example:

design crop ^
  --input ./figma-screen.png ^
  --output ./figma-screen-cropped.png ^
  --bottom 20

Crop is lossless and uses only integer edge offsets.

Exit behavior

Exit codes:

• 0 comparison passed, or render-only flow completed successfully
• 1 comparison failed acceptance, or processing produced an error

Even on 1, the CLI still writes all available artifacts and comparison-report.json.

Terminal output

The CLI prints:

• run status
• similarity and diff summary when comparison is enabled
• report path
• artifact paths
• errors, when present

Use --json if you want the full result as machine-readable JSON.