aywebp

Fast, zero-config CLI to convert images to WebP — one file or entire folders.

Website: kakajan.github.io/AyWebP · npm: aywebp

aywebp is a small Node.js command-line tool that turns JPEG, PNG, GIF, TIFF, BMP, and WebP files into optimized .webp images. Point it at a single file or a directory, tune quality, optionally recurse into subfolders, and optionally remove originals after a successful conversion.

Built with sharp for speed and reliable cross-platform support.

Table of contents

• Why aywebp?
• Features
• Quick start
• Installation
• Usage
• CLI reference
• Examples
• Supported formats
• Exit codes
• MCP server (AI agents)
• How it works
• Development
• Contributing
• License
• Author

Why aywebp?

WebP typically shrinks image payloads without a visible quality hit — great for websites, apps, and asset pipelines. aywebp keeps the workflow simple:

• No GUI, no config file, no server
• Works on Windows, macOS, and Linux
• Writes output next to each source file (photo.jpg → photo.webp)
• Safe defaults: skip existing outputs, delete originals only when you ask

Features

| Feature | Description | |---------|-------------| | Single file or batch | Convert one image or every image in a folder | | Recursive scan | -r / --recursive walks subdirectories | | Quality control | Default 85, adjustable from 1–100 | | Resize | -W / --width, -H / --height, or both with optional --fit | | Smart skip | Skips when .webp already exists (use --force to overwrite) | | Delete source | Optional --delete-source removes originals after success | | Re-encode WebP | Re-compress existing .webp files with --force | | Clear summary | Reports converted, skipped, failed, and deleted counts | | Script-friendly | Meaningful exit codes for CI and shell pipelines | | MCP server | aywebp-mcp exposes tools for Cursor and other AI agents | | JSON output | --json flag for structured CLI results |

Quick start

npm install -g aywebp
aywebp photo.png

Or install from GitHub:

npm install -g github:kakajan/AyWebP
aywebp photo.png

Output:

Converted: /photos/photo.png → /photos/photo.webp

Done: 1 converted, 0 skipped, 0 failed (1 total).

Installation

Requirements

• Node.js 18 or newer
• npm (included with Node.js)

Install from npm (recommended)

npm install -g aywebp

Available on npm: npmjs.com/package/aywebp

Install from GitHub

Alternative if you prefer installing from the repository:

npm install -g github:kakajan/AyWebP

Install from source

Clone the repo and link the CLI:

git clone https://github.com/kakajan/AyWebP.git
cd AyWebP
npm install
npm link

Or install globally from the cloned folder:

npm install -g .

Open a new terminal window, then verify:

aywebp --version

Run without installing

git clone https://github.com/kakajan/AyWebP.git
cd aywebp
npm install
node bin/aywebp.js --help

Usage

aywebp <path> [options]

<path> can be a file or a directory.

# One image
aywebp photo.png

# Every image in a folder (top level only)
aywebp ./images

# Include subfolders
aywebp ./images -r

# Custom quality
aywebp photo.png --quality 90
aywebp photo.png -q 90

# Overwrite existing .webp files
aywebp ./images --force

# Convert and remove originals
aywebp ./images --delete-source
aywebp photo.png -d

# Resize (keeps aspect ratio unless both dimensions are set)
aywebp photo.png -W 1200
aywebp photo.png -H 800
aywebp photo.png -W 1200 -H 800
aywebp photo.png -W 1200 -H 800 --fit cover

# Combine flags
aywebp ./assets -r -q 80 -f -d

CLI reference

| Option | Short | Default | Description | |--------|-------|---------|-------------| | --quality <number> | -q | 85 | WebP quality from 1 (smallest) to 100 (best) | | --recursive | -r | false | Scan subdirectories when <path> is a folder | | --force | -f | false | Overwrite existing .webp output files | | --delete-source | -d | false | Delete source file after a successful conversion | | --width <pixels> | -W | — | Resize to width; keeps aspect ratio if height is omitted | | --height <pixels> | -H | — | Resize to height; keeps aspect ratio if width is omitted | | --fit <mode> | — | inside | When width and height are both set: inside, cover, fill, or outside | | --enlarge | — | false | Allow upscaling images smaller than the target size | | --version | -V | — | Print version and exit | | --help | -h | — | Show help and exit |

Output location

Each input file maps to a WebP file in the same directory:

photos/
├── hero.jpg      →  photos/hero.webp
├── banner.png    →  photos/banner.webp
└── icons/
    └── logo.gif  →  photos/icons/logo.webp

Original files are kept unless you pass --delete-source.

Skip and safety rules

• If photo.webp already exists and --force is not set, that file is skipped (warning printed).
• --delete-source only removes files that were successfully converted.
• Skipped and failed files are never deleted.
• Re-encoding an existing .webp (same input/output path) never deletes the file.

Resize behavior

• Width only (-W 1200): scales to 1200px wide; height adjusts to keep aspect ratio.
• Height only (-H 800): scales to 800px tall; width adjusts to keep aspect ratio.
• Both (-W 1200 -H 800): fits within the box using --fit (default inside); aspect ratio is preserved unless you use --fit fill.
• Images are not upscaled by default; pass --enlarge to allow enlarging small sources.

Examples

Optimize a photo library

aywebp ~/Pictures/vacation -r --quality 85

Replace PNGs with WebP and remove originals

aywebp ./public/images -r --delete-source

Resize images for the web

aywebp ./public/images -r -W 1920 -q 85
aywebp ./thumbnails -r -W 400 -H 400 --fit cover

Re-compress WebP assets for production

aywebp ./dist/assets -r --force --quality 75

Use in a shell pipeline (exit code check)

aywebp ./uploads || echo "Some conversions failed"

Supported formats

| Input | Output | |-------|--------| | .jpg, .jpeg | .webp | | .png | .webp | | .gif | .webp | | .tif, .tiff | .webp | | .bmp | .webp | | .webp | .webp (re-encode with --force) |

Exit codes

| Code | Meaning | |------|---------| | 0 | Success — at least one file converted, or all inputs were skipped | | 1 | Usage or validation error (bad path, invalid quality, etc.) | | 2 | One or more conversions failed |

MCP server (AI agents)

Use aywebp from Cursor or other MCP clients via aywebp-mcp.

npm install -g aywebp

Add to Cursor MCP config — global (all projects) or project (this repo only):

| Scope | File | |-------|------| | Global | C:\Users\<you>\.cursor\mcp.json | | Project | .cursor/mcp.json in the repo |

{
  "mcpServers": {
    "aywebp": {
      "command": "aywebp-mcp",
      "env": {
        "AYWEBP_ALLOWED_ROOTS": "D:\\Projects"
      }
    }
  }
}

Reload Cursor after saving (Developer: Reload Window).

More configs (Claude Code, OpenCode, Codex, etc.): examples/mcp-configs/

Tools

| Tool | Purpose | |------|---------| | convert_images | Convert file or folder to WebP | | inspect_image | Read dimensions/format before converting | | list_convertible | Dry-run: preview what would be processed | | get_version | Version and supported formats |

Set AYWEBP_ALLOWED_ROOTS to comma-separated directories the agent may access. If unset, only process.cwd() is allowed.

Full docs: docs/mcp.md

CLI JSON mode

aywebp ./images -r --json

How it works

flowchart LR
  Input["File or folder"] --> Scan["Collect image paths"]
  Scan --> Convert["sharp → WebP"]
  Convert --> Output["Write .webp beside source"]
  Output --> Delete{"--delete-source?"}
  Delete -->|yes| Remove["Remove original"]
  Delete -->|no| Done["Done"]
  Remove --> Done

Under the hood:

1. commander parses arguments and flags
2. fast-glob discovers images when the path is a directory
3. sharp encodes each file to WebP at the chosen quality
4. A summary line reports results for batch runs

Development

git clone https://github.com/kakajan/AyWebP.git
cd AyWebP
npm install
node bin/aywebp.js path/to/image.png
npm start -- path/to/image.png

Releasing to npm

Maintainers: bump the version, publish, and push tags.

npm version patch   # or minor / major
npm publish
git push && git push --tags

Project layout:

aywebp/
├── bin/
│   ├── aywebp.js       # CLI entry point
│   └── aywebp-mcp.js   # MCP server for AI agents
├── src/
│   ├── collect-inputs.js
│   ├── convert.js
│   ├── inspect.js
│   ├── list-convertible.js
│   ├── run-conversion.js
│   ├── security.js
│   ├── constants.js
│   └── logger.js
├── docs/mcp.md
├── package.json
└── README.md

Contributing

Contributions are welcome — bug reports, feature ideas, docs improvements, and pull requests.

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes and test locally
4. Commit with a clear message
5. Open a pull request against main

Please keep changes focused and match the existing code style.

License

This project is licensed under the MIT License.

Author

kakajan

• GitHub: @kakajan

If aywebp saves you time or disk space, consider giving the repo a star — it helps others discover it.