ShortPixel Command Line Tool

ShortPixel Command Line Tool can optimize image folders from the command line, so it can be configured as a Cron (or other task scheduler) job. You need to have PHP installed in order for it to run.


Download the latest stable release from Github: ShortPixel PHP SDK and unpack it. You should find a shortpixel-php-master subfolder that was extracted from the archive. Inside shortpixel-php-master/lib you find cmdShortpixelOptimize.php which is the main script of the ShortPixel Command Line Tool.

Optimizing folders

Manually: Run the following commands, while in the site's root folder:

cd shortpixel-php-master/lib
php cmdShortpixelOptimize.php --apiKey=<<YOUR_API_KEY>> --folder=<<FOLDER_PATH>>

The Command Line Tool accepts the following parameters:

Parameter Meaning
apiKey Required. Your API Key. If you don't have one yet, you can request one for free in our Sign-up page.
folder Required. The path of the folder, either full or relative to the current folder. You need to have write rights to all files and subfolders in it.
compression Optional. The compression level, 1 for lossy (default), 2 for glossy and 0 for lossless. Defaults to 1 - Lossy.
Specify as --compression=1
resize Optional. Resize the images if they are larger than the specified [width] or [height], [type] being 1 for outer resize (default) and 3 for inner resize (More details)
Specify as --resize=[width]x[height] or --resize=[width]x[height]/[type]
createWebP Optional. Create additional WebP versions of the images. Specify as --createWebP
createAVIF Optional. Create additional AVIF versions of the images. Specify as --createAVIF. Added in version 1.7.
targetFolder Optional. The absolute path of the destination folder where the optimized files will be saved. If specified, cannot be either a subfolder or a parent folder of the source folder. If not specified, the original images will be overwritten by the optimized images.
Specify as --targetFolder=/path/to/destination/folder/
webPath Optional. Map the folder to a web URL and have the ShortPixel servers download the images instead of posting them (less heavy on memory for large files).
Specify as --webPath=http://yoursites.address/img/folder/
backupBase Optional. The full path of the base directory where where you can back up the optimized images. If the backupBase is outside the folder, the name of the source folder will be created as subdirectory. If it's the parent of the source folder, a folder with the _SP_BKP suffix will be created alongside the source folder. If it's inside the source folder, a ShortPixelBackups subfolder will be created and backups will be stored there. If backupBase is not specified, no backup copies are made.
Specify as --backupBase=/path/to/backup/folder/
speed Optional. Set between 1 and 10 - default is 10; but if you have large images it will eat up a lot of memory when creating the post messages, so sometimes you may need to lower it. Not needed when using the webPath mapping.
Specify as --speed=X
exclude Optional. Comma separated list of subfolders to exclude.
Specify as --exclude=folders,to,exclude
recurseDepth Optional. How many subfolders down to go into the optimized folder. Defaults to infinity, set 0 if you don't want to optimize subfolders, 1 for first level of subfolders, etc.
Specify as --recurseDepth=0
verbose Optional. Display info about the files optimized. Specify as --verbose
clearLock Optional. Clear a lock that's already placed on the folder. BE SURE you know what you're doing, files might get corrupted if the previous script is still running. The locks expire in 6 minutes. Specify as --clearLock
retrySkipped Optional. Retry all skipped items, regardless of their retry count (reset it to 0). Not recommended as parameter to a cron job, might block indefinitely on items that won't process, because it will never skip them. Usually run once - for example after you detected a rights problem for some files and fixed it. Specify as --retrySkipped

The Command Line Tool will fallback to the .sp-options file for additional options; if an option is specified in the command line but is present also in the .sp-options file, the command-line value will prevail (but it will not update the .sp-options file). The .sp-options file should be present in the destination folder (or either the source or destination folder starting from version 1.6.4) and has the following structure:


The base_url from .sp-options corresponds to the command-line parameter --webPath

Cron job: add the same command to your scheduler, optionally appending  2>&1 1>/your/log/file. The ShortPixel Command Line Tool has a locking mechanism in place, so if another instance is already running on the same folder, it exits.

ShortPixel Knowledge Base