Licence
MIT
Version
0.1.0
Deps
0
Size
16 kB
Vulns
0
Weekly
0
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 0Why "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