NanoImage CLI Documentation

Install and use NanoImage CLI to compress, resize, convert, and clean images from the command line.

Overview

NanoImage CLI is a command-line image optimization tool. It runs locally on your machine and processes files without any uploads.

CLI v1 includes five commands:

compress — Reduce image file size
resize — Change image dimensions
convert — Convert between formats
webp — Convert to WebP
remove-exif — Strip metadata

All commands support single files and directories. For one file, --output can be a file path. For a folder, --output should be an output directory.

Installation

Requires Node.js 18 or later.

Install globally with npm:

npm install -g nanoimage

Or use without installing:

npx nanoimage --help

Verify the install:

nanoimage --version

Quick start

One example for each command:

nanoimage compress photo.jpg --quality 75 --output photo-compressed.jpg

nanoimage resize photo.jpg --width 1200 --output photo-1200.jpg

nanoimage convert photo.png --to jpg --output photo.jpg

nanoimage webp photo.jpg --quality 80 --output photo.webp

nanoimage remove-exif photo.jpg --output photo-clean.jpg

compress

Compress an image or a folder of images.

Usage

nanoimage compress <input> [options]

Examples

nanoimage compress photo.jpg --quality 75 --output photo-compressed.jpg

nanoimage compress photo.jpg --target-kb 100 --output photo-100kb.jpg

nanoimage compress ./images --quality 75 --output ./compressed

Options

Option	Description
`--quality, -q`	Output quality from 1 to 100
`--target-kb`	Best-effort target output size in KB
`--output, -o`	Output file or directory

Notes: --target-kb is best-effort. Some images may not reach the requested size without resizing or very low quality.

resize

Resize images by width or height. Aspect ratio is kept by default when only one dimension is provided.

Usage

nanoimage resize <input> [options]

Examples

nanoimage resize photo.jpg --width 1200 --output photo-1200.jpg

nanoimage resize photo.jpg --height 800 --output photo-800h.jpg

nanoimage resize ./images --width 1600 --output ./resized

Options

Option	Description
`--width, -w`	Target width in px
`--height, -h`	Target height in px
`--fit`	Sharp fit mode: inside, contain, cover, fill, or outside
`--enlarge`	Allow enlarging images smaller than the target size
`--output, -o`	Output file or directory

Notes: If only width is provided, height is calculated automatically. If only height is provided, width is calculated automatically.

convert

Convert images between common formats.

Usage

nanoimage convert <input> --to <format> [options]

Examples

nanoimage convert input.png --to jpg --output output.jpg

nanoimage convert logo.png --to jpg --background white --output logo.jpg

nanoimage convert ./images --to webp --quality 80 --output ./converted

Options

Option	Description
`--to`	Target format: jpg, png, webp, or avif
`--output, -o`	Output file or directory
`--quality, -q`	Quality for JPG/WebP
`--background`	Background color when converting transparency to JPG

Notes: JPG does not support transparency. Transparent PNG or WebP converted to JPG will use a white background by default unless --background is specified.

webp

Convert images to WebP. This is a shortcut for a common web optimization workflow.

Usage

nanoimage webp <input> [options]

Examples

nanoimage webp hero.jpg --quality 80 --output hero.webp

nanoimage webp ./images --quality 82 --output ./webp

nanoimage webp ./public/images --quality 82 --remove-exif --output ./public/images-webp

Options

Option	Description
`--quality, -q`	WebP quality from 1 to 100
`--output, -o`	Output file or directory
`--remove-exif`	Remove metadata during conversion

Notes: WebP is recommended for websites and blogs. Use --quality to balance visual quality and output size.

remove-exif

Remove common EXIF metadata from images. Useful before publishing personal, product, or website images.

Usage

nanoimage remove-exif <input> [options]

Examples

nanoimage remove-exif photo.jpg --output photo-clean.jpg

nanoimage remove-exif ./uploads --output ./uploads-clean

Options

Option	Description
`--output, -o`	Output file or directory

Notes: Removes common EXIF metadata. Does not guarantee every possible metadata field in every format.

Batch processing

All commands accept a directory as input. Pass a folder path and an output folder.

nanoimage compress ./images --quality 75 --output ./compressed

nanoimage resize ./images --width 1200 --output ./resized

nanoimage webp ./images --quality 80 --output ./webp

Directory inputs are processed recursively by default.

For single-file inputs, --output can be a file path such as photo-compressed.jpg. For folder inputs, use an output directory such as ./compressed.

JSON output

Add --json to any command for machine-readable output. Useful for CI/CD, build scripts, logs, and AI agent workflows.

nanoimage compress photo.jpg --quality 75 --json

Example output:

[
  {
    "input": "photo.jpg",
    "output": "photo-compressed.jpg",
    "inputSize": 2457600,
    "outputSize": 524288
  }
]

CI/CD usage

Add NanoImage CLI to your package.json scripts:

{
  "scripts": {
    "optimize-images": "nanoimage compress ./public/images --quality 75 --output ./public/images-optimized"
  }
}

GitHub Actions example:

name: Optimize Images

on: [push]

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g nanoimage
      - run: nanoimage compress ./public/images --quality 75 --output ./public/images-optimized

Troubleshooting

Error	Meaning	Fix
`Unsupported format`	Input format not supported	Use JPG, PNG, or WebP
`Cannot write output`	Permission or path issue	Check folder permissions
`Input not found`	File path is wrong	Check the input path
`Processing failed`	Image decode/encode failed	Try another file or format

FAQ

Does NanoImage CLI upload my images?

No. CLI processing happens entirely on your local machine. Files are never sent to any server.

Can I use it in CI/CD?

Yes. Use commands in npm scripts, build pipelines, or GitHub Actions. The --json flag gives machine-readable output for automation.

Which image formats are supported?

CLI v1 focuses on JPG, PNG, and WebP. More formats may be added in future versions.

Can I process entire folders?

Yes. Pass a directory as input and an output directory. Directories are processed recursively by default.

Ready to optimize images from your terminal?

npm install -g nanoimage

CLI overview Read launch post