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/[email protected]
        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