Getting Started Development Help & Support

CLI Reference

Automate batch image compression and format conversion with the imgcompress CLI. Process thousands of images from terminal scripts or CI/CD pipelines — runs entirely on your self-hosted server with no cloud dependency.

Get StartedAutomation

When to use the CLI#

The CLI is for automation and batch processing. If you're converting thousands of images or building a script, it's faster and more flexible than the web UI.

ℹ️New to imgcompress?

Start with the Web UI. Come back here when you want to automate.

How it works#

The CLI runs inside the Docker container. To access your local files, you mount your folder using the -v flag:

$(pwd): your current local folder
/container/images: where the container reads input files
/container/done: where the container writes output files

💡Pull the latest image first

Before running any of the examples below, refresh your local image so you're not running an old version:

bash
docker pull karimz1/imgcompress:latest

Examples#

Convert a single image#

bash
docker run --rm \
  -v "$(pwd):/container/images" \
  -v "$(pwd)/done:/container/done" \
  karimz1/imgcompress:latest \
  cli \
  /container/images/photo.jpg \
  /container/done \
  --quality 80 \
  --format png

Convert an entire folder#

bash
docker run --rm \
  -v "$(pwd):/container/images" \
  -v "$(pwd)/done:/container/done" \
  karimz1/imgcompress:latest \
  cli \
  /container/images \
  /container/done \
  --format jpeg \
  --quality 85

Remove backgrounds from a folder#

bash
docker run --rm \
  -v "$(pwd):/container/images" \
  -v "$(pwd)/done:/container/done" \
  karimz1/imgcompress:latest \
  cli \
  /container/images \
  /container/done \
  --format png \
  --remove-background

Options#

Flag	Description
`--quality`	Compression quality, 1-100. Higher = better quality, larger file.
`--width`	Resize to this width in pixels. Aspect ratio is preserved.
`--format`	Output format: `jpeg`, `png`, `webp`, `avif`.
`--remove-background`	Use local AI to remove the image background.
`--json-output`	Output structured JSON, useful for piping results into other programs or scripts.

For Code Wizards#

Add --json-output at the end of any command to get results that other programs can read easily. Instead of plain text, imgcompress returns a structured JSON response with paths, sizes, and status for every file. Perfect for shell pipelines, CI jobs, or any tool that consumes JSON.

bash
docker run --rm \
  -v "$(pwd):/container/images" \
  -v "$(pwd)/done:/container/done" \
  karimz1/imgcompress:latest \
  cli \
  /container/images \
  /container/done \
  --format webp \
  --quality 85 \
  --json-output

Privacy & Safety

Release Notes