Command Line (jpgboost-cli)

jpgboost-cli compresses your images without launching the graphical interface. It's the tool to reach for with scripts, scheduled tasks, and continuous integration pipelines.

Pro Feature

Your licence covers up to two installations that you use personally. The app and the CLI each count as a distinct installation, even when both are installed on the same Mac. They appear as devices in Settings > Licence.

A server that runs only the CLI for your own automations, such as continuous integration or a scheduled task, can therefore occupy one of these two installations without requiring an additional licence. For more information, see the Licence on a server and One licence per user sections.

What the command line is for

jpgboost-cli is a self-contained executable, shipped inside JPGBoost.app. It depends neither on the local API nor on a running instance of the app: it uses the same decoding and encoding engine directly, so it produces exactly the same files as the graphical interface.

It's the entry point to reach for whenever no interface should open: a shell script, a scheduled task, a continuous integration pipeline, processing a large number of files.

Nothing to install

jpgboost-cli is included in JPGBoost.app. No compilation or library installation is needed, since it uses the components already built into the app.

Making the command accessible

The binary lives inside the app bundle. You can call it directly by its full path:

/Applications/JPGBoost.app/Contents/MacOS/jpgboost-cli --help

To be able to run jpgboost-cli from any folder, create a symbolic link once:

sudo ln -s /Applications/JPGBoost.app/Contents/MacOS/jpgboost-cli \
  /usr/local/bin/jpgboost-cli

jpgboost-cli --help

Since the link points into the bundle, it stays valid after an app update. The examples on this page assume this setup; without it, replace jpgboost-cli with the full path above.

If you don't use sudo

You can target a personal folder instead of /usr/local/bin, for example ~/bin, as long as it's on your PATH. A simple alternative is to add an alias to your ~/.zshrc.

Licence on a server

A machine that runs only the CLI, for example a server with no graphical interface, can be activated and managed without using JPGBoost.app.

# This machine's identifier, from the CLI
jpgboost-cli --machine-id

# First activation, with the token received by email after purchase
jpgboost-cli --activate ACT-XXXX-XXXX-XXXX-XXXX-XXXX

# From this already-activated server, generate a code to add another device
jpgboost-cli --add-device

# Join a licence using a code generated elsewhere (app or another CLI)
jpgboost-cli --pair XXXX-XXXX

# Fetch a newer version of the licence if the server has one
jpgboost-cli --sync

# Number of installations used / limit, and their list — read locally, no network call
jpgboost-cli --devices

The app and the CLI count as two distinct installations

The app and the CLI are considered two distinct installations, even when used on the same Mac. Each has its own installation identifier and therefore takes up one of the two slots allowed by a Pro licence.

You can use your licence in different ways, for example with the app on your Mac and the CLI on a server, with the app and the CLI on the same Mac, with the app on two different Macs, or with the CLI alone on a server that never opens the app.

Syntax and options

jpgboost-cli <file...> --output <folder> [options]

Option	Purpose	Default
`--output <folder>`	Destination folder, created if it doesn't exist	Required
`--quality <1-100>`	Compression quality	75
`--format <format>`	`png`, `jpeg`, `heic`, `avif`, `webp`, or `jxl`	`jpeg`
`--profile <name>`	Applies a named export profile	None
`--jobs <N>`	Files processed in parallel	Number of cores
`--json`	Structured JSON output instead of readable text	Off
`--help`	Shows help	—

First examples

# Two files to WebP, quality 60
jpgboost-cli photo1.jpg photo2.png --quality 60 --format webp --output ./compressed
# photo1.jpg: 4.2 MB -> 890 KB (-79%) -> ./compressed/photo1.webp
# photo2.png: 1.8 MB -> 620 KB (-66%) -> ./compressed/photo2.webp
#
# 2 file(s) processed, 0 failure(s).

# A whole folder to AVIF
jpgboost-cli ~/Images/export/*.png --format avif --quality 65 --output ~/Images/web

Batch processing and parallelism

For hundreds or thousands of files, the --jobs option processes several images at once. Each file is decoded, encoded, and then released independently: memory footprint doesn't grow with the number of files waiting, only with the value of --jobs.

# Eight files processed at the same time
jpgboost-cli ~/Photos/batch/*.jpg --jobs 8 --format webp --output ~/Photos/web

# One at a time, to limit load on a shared machine
jpgboost-cli ~/Photos/batch/*.jpg --jobs 1 --format webp --output ~/Photos/web

Measured gain

On a batch of 12 files, --jobs 8 turned out to be roughly four times faster than --jobs 1. The actual gain depends on your Mac's core count and the target format: AVIF and JPEG XL are noticeably slower to encode than JPEG or HEIC.

Using an export profile

The --profile option reuses a profile created in the app or via the API. It only fills in what you haven't explicitly specified.

# Format, quality, and folder all come from the profile
jpgboost-cli --profile "Web JPEG" *.png

# The explicit folder wins, the rest comes from the profile
jpgboost-cli --profile "Web JPEG" --output ./de/livery *.png

The CLI can also create or update a profile directly, without going through Settings or the local API:

jpgboost-cli --create-profile "Web JPEG" --format jpeg --quality 70 --output ./compressed

--format and --quality are required, --output is optional (the given folder must already exist). A name already in use overwrites the existing profile instead of creating a duplicate — the same behaviour as the app's Profiles tab and the local API. Requires JPGBoost Pro, like the rest of the CLI.

JSON output

With --json, the output is a JSON array in which each processed file corresponds to a JSON object, with the same shape as the local API's responses, which makes chaining with jq or any other tool easier.

jpgboost-cli *.png --format webp --output ./out --json

# Chaining with jq: keep only files with an error
jpgboost-cli *.png --format webp --output ./out --json \
  | jq '.[] | select(.error != null)'

Available fields: path, originalSizeBytes, compressedSizeBytes, ratio, destination, and error.

Exit codes

Code	Meaning
`0`	All files were processed successfully
`77`	No valid Pro licence on this machine
Non-zero	At least one file failed; usable directly in a script or continuous integration

Files with the same name

Two input files sharing the same base name naturally target the same output. a/photo.jpg and b/photo.png converted to WebP would both produce photo.webp.

JPGBoost doesn't overwrite them: the second one gets a distinct name.

a/photo.jpg  ->  photo.webp
b/photo.png  ->  photo-2.webp

Names are assigned in argument order, independent of execution order with --jobs, so the result is reproducible. The same rule applies in the app, Shortcuts, AppleScript, and watched folders.

Re-running the same export

This rule only concerns collisions between different files. Re-exporting the same file to the same folder does overwrite its previous output, without piling up photo-2, photo-3, and so on.

Verifying the install

Check at any time that the command responds correctly:

jpgboost-cli --help