sharp-cli

5.2.0 verified Sat Apr 25 auth: no javascript

sharp-cli is a command-line interface for the sharp library, a high-performance Node.js image processing module that uses libvips. Version 5.2.0 supports conversion and manipulation of JPEG, PNG, WebP, AVIF, TIFF, GIF, and SVG images. It provides commands for resizing, cropping, rotating, blurring, compositing, and other common image operations. The CLI mirrors most sharp API features, including input options like auto-orient and output options like smart-deblock. It follows sharp's release cadence and requires Node.js >= 18.17. Compared to alternatives like ImageMagick or GraphicsMagick, sharp-cli leverages libvips for speed and memory efficiency, with a focused, modern command set.

Common errors

error Error: Input file is required ↓

cause No input file provided to sharp command

fix

Specify an input image file as the first argument, e.g., sharp input.jpg resize 300 200 output.jpg

error Command not found: sharp ↓

cause sharp-cli not installed globally or npx not used

fix

Install globally: npm install -g sharp-cli, or use npx sharp

error Error: Unknown argument: --resize 300 ↓

cause Incorrect argument syntax for resize command

fix

Use: sharp resize <width> <height>, e.g., sharp input.jpg resize 300 200 output.jpg

Warnings

breaking Node.js version requirement increased to 18.17+ in v5.0.0 ↓

fix Update Node.js to version 18.17 or later.

breaking In v4.0.0, --band was renamed to --channel for extractChannel command ↓

fix Use --channel instead of --band.

gotcha If sharp-cli is not installed globally, commands must be prefixed with npx ↓

fix Install globally with npm install -g sharp-cli or use npx sharp.

breaking v3.0.0 dropped support for Node.js < 14.15 ↓

fix Upgrade Node.js to at least 14.15.

deprecated --withMetadata input option renamed to --metadata in v4.1.0 ↓

fix Use --metadata instead of --withMetadata.

Install

npm install sharp-cli

yarn add sharp-cli

pnpm add sharp-cli

Imports

sharp command line
wrong
```
sharp --help
```
correct
```
npx sharp --help
```
If sharp-cli is not globally installed, use npx or install globally first.

Resize an image

wrong

sharp input.jpg --resize 300 --resize 200 output.jpg

correct

sharp input.jpg --resize 300 200 output.jpg

Use --resize with two arguments (width height), not two separate flags.

Composite with multiple images

wrong

sharp input.jpg composite overlay1.png output.jpg composite overlay2.png output.jpg

correct

sharp input.jpg composite overlay1.png overlay2.png output.jpg

Since v4.0.0, composite accepts multiple image arguments directly.

Quickstart

Resize an image to 300x200, rotate 90 degrees and convert to WebP, and extract a region from a TIFF.

npx sharp-cli input.jpg resize 300 200 -o output.jpg
npx sharp-cli input.png --rotate 90 --format webp -o rotated.webp
npx sharp-cli input.tif --resize 800 600 --extract 50 50 200 200 output.png