How to Optimize Images with ShortPixel CLI

If you’re building or maintaining a website with a lot of images, you already know how tedious manual optimization can get. Upload, compress, download, replace, repeat. For a handful of images it’s fine, but when you’re dealing with hundreds or thousands, it doesn’t scale.

That’s where the ShortPixel CLI comes in.

It’s a bash script that connects directly to the ShortPixel API and batch-optimizes all the images in a folder and even all the subfolders within it. You can use it locally on your machine, run it on a server, or set it up as a cron job so everything happens automatically in the background.

This makes it ideal for developers, agencies, or anyone managing large image libraries outside of WordPress.

The best part? It’s a single file. No Node.js, no Python, no package managers. Just bash and curl,  both already available on pretty much any Linux or macOS system.

Key features

At its core, the script scans a directory and all its subdirectories for images, uploads each one to the ShortPixel API, and downloads the optimized version. But it does quite a bit more than that:

• It processes multiple images in parallel, so even large folders are handled efficiently.
• It tracks what’s already been optimized using per-folder .splog state files, so re-runs skip files that are already done.
• It backs up every original before touching it. If anything goes wrong, you can restore with one command.
• It shows an analytics dashboard on every run with file counts, space savings, and errors.
• It can email you that report automatically, handy when running scheduled jobs overnight.

Getting started

1. Clone the repository

Head over to the GitHub repo and clone it:

git clone https://github.com/short-pixel-optimizer/shortpixel-sh.git

cd shortpixel-sh

chmod +x shortpixel-optimize.sh

2. Run the onboarding wizard

The first time you run the script with a terminal attached, it launches an interactive setup wizard. It walks you through everything: your API key, compression level, number of parallel workers, backup preferences, output settings, and email notifications.

./shortpixel-optimize.sh

Every prompt has a sensible default you can accept by pressing Enter. When it’s done, the wizard writes a fully commented .env file in the script’s directory. If you ever want to re-run the wizard, just delete the .env and start again.

Here’s what the wizard covers:

1. API key — loops until you provide one (this is the only required value).
2. Compression — lossy, lossless, or glossy. Also whether to keep EXIF metadata.
3. Processing — how many parallel workers (default: 4) and the API polling interval (default: 25 seconds).
4. Output — overwrite originals, or save to a separate folder. Also which extensions to exclude.
5. Backups — enable/disable, and where to store them (default: ./backups).
6. Email — optional address for the post-run analytics report. The script auto-detects mail or sendmail and offers to send a test email.

Don’t have an API key yet? Grab one from your ShortPixel dashboard. The free plan gives you 100 image credits per month.

If you prefer to skip the wizard entirely, pass your key directly:

./shortpixel-optimize.sh -k YOUR_API_KEY ./images

In non-interactive environments (CI, cron), the wizard is skipped automatically.

Where do optimized files go?

The script supports three output modes:

• Default — optimized files go into an optimized/ subfolder next to the source images. These subfolders are automatically excluded from future scans.
• Custom output directory (-o ./out or OUTPUT_DIR in .env) — all optimized files go flat into the specified directory.
• Overwrite (–overwrite or OVERWRITE=true in .env) — replaces the source files in-place. Backups are always created first.

Note that –overwrite and –output-dir are mutually exclusive. The script will let you know if you try to use both.

Common use cases

Optimize a folder with multiple workers

Run 4 workers in parallel and overwrite the originals in place (backups are created automatically before anything gets replaced):

./shortpixel-optimize.sh -k YOUR_KEY --overwrite -j 4 ./images

Glossy compression with WebP conversion

Glossy mode gives you near-perfect visual quality with solid file size savings. Adding +webp generates a WebP version alongside the original format:

./shortpixel-optimize.sh -k YOUR_KEY -l 2 -o ./out --convertto +webp ./images

Re-optimize everything from scratch

The –force flag ignores the state files and reprocesses every image, even ones that were already optimized:

./shortpixel-optimize.sh --force --overwrite ./images

Restore originals from backup

Changed your mind? This copies every backup file back to its original location and writes a restore_audit.log so you have a record of what was restored:

./shortpixel-optimize.sh --restore ./images

The analytics dashboard

Every time the script finishes, whether it completes normally, hits an error, or gets interrupted it prints a summary showing:

• How many files were processed, failed, skipped (already optimized), or excluded (by extension)
• Any folders that were skipped due to permission issues
• Total space saved: original size vs. optimized, in MB or GB
• Combined footprint of current source files plus the backup directory

If you’ve set the EMAIL variable, this same report gets sent to your inbox automatically. The script detects whether mail or sendmail is available, or you can set MAIL_CMD explicitly in your .env.

FAQs

If you’re working with large image sets or need full automation, ShortPixel CLI gives you a simple and reliable way to optimize everything at scale. You can find the full script and documentation on GitHub and start optimizing your images in minutes.