imagedimensions-cli

imagedimensions-cli

Audit the images on any web page from the command line — find oversized images (downloaded much larger than they display, the most common Largest Contentful Paint problem) and fail CI when new ones slip in. Powered by imagedimensions.com; the scan runs server-side, so no local browser is required.

Quick start

npx imagedimensions-cli https://example.com

⚠ https://example.com
  58 images (41 visible) · 7% WebP/AVIF · 9/37 oversized (≥4× area)
      102.0×  4000x3000 → 400x300  [jpg]  https://example.com/hero.jpg
       18.4×  1600x1200 → 372x279  [png]  https://example.com/card.png
  report: https://imagedimensions.com/results?scanId=…

Options

Flag	Description
--threshold <n>	Area-overshoot ratio that counts as oversized. Default 4 (≈2× per dimension).
--max-oversized <n>	Exit 1 if any URL has more than n oversized images. Omit to never fail.
--top <n>	Max oversized images to list per URL. Default 10.
--json	Machine-readable JSON output.
--api-base <url>	Override the scan API base (or IMAGEDIMENSIONS_API_BASE).

Exit codes: 0 success · 1 --max-oversized gate exceeded · 2 scan failed / bad args.

Use in CI

Fail a pull request if the deployed preview ships any image oversized by ≥4×:

# .github/workflows/image-audit.yml
name: Image audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: Bishop81/imagedimensions-cli@v0.1.0
        with:
          url: https://staging.example.com
          max-oversized: '0'

Or call the CLI directly in any pipeline:

npx imagedimensions-cli@latest "$DEPLOY_URL" --max-oversized 0

Why "oversized" matters

An image downloaded much larger than its rendered box wastes bandwidth and decode time and slows LCP. Right-size to the display dimensions, add srcset, and convert to a modern format. Background: Stop shipping 4000px images into 400px slots.

License

MIT