@puntoycoma/bulki

The image optimizer that works the way you do — interactively, automatically, or as a tool your AI editor calls for you.

Compress, resize, and convert JPEG, PNG, WebP, GIF, and AVIF images in bulk. Powered by Sharp (libvips) — 4-5x faster than ImageMagick.

Free. Open source. No API keys. Runs 100% locally.

npm install -g @puntoycoma/bulki

At a glance

| Feature | What it does | Command | |---------|-------------|---------| | Compress | Optimize images with quality, format, and resize control | bulki compress ./photos -f webp -q 80 | | Interactive | Guided menu with presets — no flags to memorize | bulki | | Watch | Monitor a folder and auto-optimize new images | bulki watch ./uploads -f webp | | Pipe | Read from stdin, write to stdout — compose with any tool | cat img.jpg \| bulki pipe -f webp > out.webp | | Git hook | Auto-optimize images on every commit | bulki hook install | | MCP server | Let AI editors (Claude Code, Cursor) call bulki directly | bulki mcp | | JSON output | Machine-readable results for scripts and CI/CD | bulki compress ./imgs --json | | Size budget | Fail if any image exceeds a size limit | bulki compress ./imgs --max-size 200kb |

Quick start

Interactive mode

bulki

Guided menu with presets:

• Web optimized — WebP, quality 80, max 1920px
• Social media — PNG, quality 85, max 1080px
• Custom — you choose everything

CLI mode

bulki compress ./photos                    # optimize with defaults
bulki compress ./photos -f webp -q 80      # convert to WebP
bulki compress ./photos -r 1920 -q 85      # resize to 1920px
bulki compress hero.png -f avif -q 70      # single file to AVIF

Compress

Optimize one file or an entire directory. Preserves folder structure.

bulki compress <path> [options]

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --quality <n> | -q | Output quality (1-100) | 70 | | --format <fmt> | -f | jpeg, png, webp, gif, avif | original | | --resize <width> | -r | Max width in pixels | original | | --destination <path> | -d | Output base directory | . | | --output-folder <name> | -o | Output folder name | bulki-output | | --concurrency <n> | | Parallel operations (1-32) | auto | | --exclude <patterns...> | | Directory names to skip | none | | --dry-run | | Preview without writing | false | | --verbose | | Per-file details | false | | --json | | Machine-readable JSON output | false | | --max-size <size> | | Fail if output exceeds limit (e.g., 200kb, 1mb) | none |

Output preserves your folder structure:

photos/                    bulki-output/
  vacation/         ->       vacation/
    beach.jpg                  beach.jpg
    sunset.png                 sunset.png

Examples

# Optimize for web: WebP, quality 80, max 1920px
bulki compress ./public -f webp -q 80 -r 1920

# Preview what would be processed without writing anything
bulki compress ./uploads --dry-run

# Get JSON results for a script
bulki compress ./images --json

# Fail in CI if any image exceeds 200 KB
bulki compress ./assets --max-size 200kb

JSON output

bulki compress ./images --json

{
  "files": [
    {
      "input": "photo.jpg",
      "output": "bulki-output/photo.webp",
      "originalSize": 2400000,
      "newSize": 680000,
      "reduction": 72,
      "format": "webp"
    }
  ],
  "summary": {
    "totalFiles": 1,
    "totalOriginalSize": 2400000,
    "totalNewSize": 680000,
    "totalReduction": 72,
    "errors": 0
  }
}

Watch

Monitor a directory. Every time a new image appears, bulki optimizes it automatically. Runs until you press Ctrl+C.

bulki watch <directory> [options]

Same options as compress: --quality, --format, --resize, --destination.

Examples

# Watch uploads and convert everything to WebP
bulki watch ./uploads -f webp -q 80

# Watch with resize, output to a different folder
bulki watch ./photos -r 1920 -q 85 -d ./optimized

Use cases

• Photographers — import photos from camera to a folder, get optimized versions automatically
• Designers — export from Figma or Sketch, images optimize as they save
• Upload servers — monitor /var/uploads and serve optimized versions from /var/optimized
• Content teams — shared folder where anyone drops images and they come out ready for web

Pipe

Read an image from stdin, optimize it, write the result to stdout. No files on disk.

bulki pipe -f <format> [-q quality] [-r width]

Examples

# Download and optimize in one command
curl -s https://example.com/photo.jpg | bulki pipe -f webp -q 80 > photo.webp

# Convert format on the fly
cat input.png | bulki pipe -f avif -q 70 > output.avif

# Optimize and upload to S3 without saving locally
cat photo.jpg | bulki pipe -f webp -r 800 | aws s3 cp - s3://bucket/photo.webp

Use cases

• CI/CD pipelines — optimize images during build without temp files
• Shell scripts — compose with curl, aws, gsutil, scp, or any Unix tool
• Webhooks — receive an image from an HTTP request, optimize, forward

Git hook

Install a pre-commit hook that auto-optimizes every image you commit. One command. Works for the entire team.

bulki hook install       # add the hook
bulki hook uninstall     # remove it

How it works

1. You run bulki hook install once in your repo
2. Every time someone runs git commit with staged image files (JPEG, PNG, WebP, GIF, AVIF), bulki optimizes them before the commit completes
3. The optimized version replaces the original in the commit
4. No manual step — it just works

Use cases

• Teams — ensure no one ever commits unoptimized images
• Repository health — keep your repo lean without manual work
• Faster CI/CD — smaller images in the repo = faster clones, builds, and deploys

MCP server (AI editor integration)

bulki includes a built-in MCP server. AI coding assistants call bulki directly — no shell commands, no copy-paste.

Runs 100% locally. No API keys. No internet required.

Works with Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible editor.

bulki mcp

Setup

Add to your editor's MCP config:

Claude Code (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "bulki": {
      "command": "npx",
      "args": ["@puntoycoma/bulki", "mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "bulki": {
      "command": "npx",
      "args": ["@puntoycoma/bulki", "mcp"]
    }
  }
}

Then ask your AI:

"Optimize all images in the project for web" "Convert the PNG files in /public to WebP" "Check if any image in /assets is larger than 200kb"

Available tools

| Tool | Description | |------|-------------| | compress | Optimize images with format, quality, resize, and size budget options | | detect | Identify if a file is an image and return its format |

Integration examples

npm scripts

{
  "scripts": {
    "images": "bulki compress ./src/assets -f webp -q 80",
    "images:check": "bulki compress ./public --max-size 200kb --dry-run"
  }
}

GitHub Actions

- name: Optimize images
  run: npx @puntoycoma/bulki compress ./public -f webp -q 80 --max-size 500kb

CI pipeline with JSON

result=$(bulki compress ./dist/images --json --max-size 300kb)
echo "$result" | jq '.summary.totalReduction'

Supported formats

| Format | Compress | Convert to | Convert from | |--------|----------|------------|--------------| | JPEG | yes | yes | yes | | PNG | yes | yes | yes | | WebP | yes | yes | yes | | GIF (animated) | yes | yes | yes | | AVIF | yes | yes | yes |

Requirements

• Node.js >= 20

FAQ

How do I convert images to WebP from the command line? bulki compress ./images -f webp -q 80

What's the best free alternative to TinyPNG? bulki — runs locally, no file limits, no API keys. bulki compress ./photos -q 80

How do I optimize images for web performance? bulki compress ./public -f webp -q 80 -r 1920 --max-size 500kb

How do I auto-optimize images in my project? bulki hook install for git commits, or bulki watch ./uploads for a live folder.

Can AI editors optimize images? Yes. Add bulki as an MCP server to Claude Code, Cursor, or Windsurf. Ask: "optimize the images in /public".

What formats does bulki support? JPEG, PNG, WebP, GIF (animated), and AVIF. Compression and conversion between all formats.

Is imagemin still maintained? No. imagemin and its plugins are deprecated. bulki is a modern, maintained alternative.

License

AGPL-3.0 — free to use, modify, and distribute. All derivatives must remain open source under the same license. See LICENSE for details.

Contributing

Issues and PRs welcome at github.com/PuntoyComaTech/bulki.

Developed by PuntoyComaTech

A free tool for developers, designers, and teams who care about performance.