image-diff-cli

Fast screenshot versioning and visual diffs for UI work. 📸

image-diff-cli watches a folder for new screenshots, auto-versions each capture, and lets you compare the latest changes instantly.

Why it helps

• No manual renaming: screenshots become session_V1, session_V2, ...
• Immediate visual history: side-by-side output is rebuilt automatically
• Quick diff inspection: open horizontal or vertical slider views from the keyboard
• Great for rapid UI iteration loops

Quick start ⚡

Run directly with npx:

npx image-diff-cli

Typical run for Desktop screenshots:

npx image-diff-cli -d ~/Desktop

Browser viewer mode (auto-updating):

npx image-diff-cli -d ~/Desktop --web

What happens next:

1. New screenshots (.png, .jpg, .jpeg) are detected
2. Files are moved into your session output folder
3. Versioned files are saved as <session>_V{n}.png
4. <session>_iterations.png is regenerated
5. You can open diff views with keyboard shortcuts

Command options ⚙️

• -d, --dir <path>: directory to watch (default: .)
• -o, --output <path>: output root directory (default: ./output)
• -n, --name <sessionName>: session name for folder/files (prompts if omitted in interactive mode)
• --on-exists <policy>: behavior when session directory exists (prompt, fail, reuse, increment)
• --no-interactive: disable prompts and key controls
• --web: start local browser viewer with live updates
• --web-port <port>: browser viewer port (default: 4738)
• --debug: print startup/debug information
• -h, --help: show help

Live web viewer

When --web is enabled, the CLI starts a local viewer (for example http://127.0.0.1:4738) and opens it in your browser.

• Horizontal mode: compares latest 2 screenshots
• Vertical mode: compares latest 2 screenshots
• Pixel diff mode: highlights changed pixels between latest 2 screenshots
• Side-by-side mode: shows all screenshots in the session (horizontal scroll)
• New screenshots appear automatically without manual reload

Interactive keys ⌨️

• h: open horizontal slider diff (last 2 images)
• v: open vertical slider diff (last 2 images)
• p: generate and open pixel diff image (last 2 images)
• b: open side-by-side image (<session>_iterations.png)
• q or Ctrl+C: quit

Typical workflow

1. Start one session per task or feature (-n checkout, -n auth, etc.)
2. Make a UI change
3. Take a screenshot
4. Press h/v/p/b to inspect changes
5. Repeat until done

Notes

• Built for local development, not CI image regression baselining
• Most useful when screenshots are captured with a consistent viewport/area