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

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

💡Pipe into jq

Chain --json-output with jq to extract exactly what you need:

bash
# Print just the output file paths
docker run --rm ... --json-output | jq '.files[].output_path'

# Print original vs compressed size for every file
docker run --rm ... --json-output | jq '.files[] | {file: .output_path, saved: (.original_size - .output_size)}'

ℹ️Works great in CI/CD

Use --json-output in GitHub Actions or any pipeline to assert on file sizes, catch regressions, or forward results to another step without parsing plain text.

Privacy & Safety

Release Notes