WP-CLI support for ShortPixel Image Optimizer
Starting with ShortPixel Image Optimizer (SPIO) version 5, we introduced support for WP-CLI for various operations that the plugin performs. If you have not used WP-CLI before, please read this Quick Start Guide and see the installation and overall documentation of this tool.
Start here
All WP-CLI commands of the SPIO plugin start with:
wp spio
An important detail you should know is that SPIO 5 has 4 different queues:
- Single processing Media Library queue: Newly uploaded images will go into this queue, as well as the images that you manually click "Optimize now" on in the Media Library.
- Single processing Custom Media queue: This queue contains newly added Custom Media files and images for which you click "Optimize now" in the Custom Media screen.
- Bulk processing Media Library queue: This is the queue used by the bulk system to process the items from the Media Library.
- Bulk processing Custom Media queue: This is the queue used by the bulk system to process the items from the Media Library.
Also, please note that if you have the "Optimize media on upload" option enabled in SPIO (this is the default setting), the above queues will only be processed on these admin pages! If you don't want to keep these pages open in your browser, read on, because you will see how to perform all these operations using WP-CLI commands.
In this article
General recommendations
Before proceeding with any of these commands, we strongly recommend you check the WP-CLI handbook, WP-CLI commands, and the Support area.
In additions, please take the following into account.
- Every WP-CLI command is terminated as soon as you close your terminal. If you want to run the command in the background and close the terminal, we kindly invite you to do your own research on Google, because there are several possibilities, which sometimes depend on the operating system you are using. For example:
- In case you want to use the commands below in a multisite environment, please note that by default they will run on the main site of the installation. If you want to run the commands for a secondary sub-site, then please use the
--url=<url>
parameter to specify the subsite where the commands should be executed. You can obtain information about the subsite URL using the wp site command and. - Each command that executes the optimization processes the images with the settings that you have activated in your ShortPixel settings in your WordPress administration area. This means, for example, if you want to change the image quality resulting from a WP-CLI command, you must first change it in your WordPress admin area and only then run the WP-CLI command.
When running the WP-CLI commands mentioned below it is very important to run them with the same user that owns the files of your site. Otherwise, you may end up with file permission issues that can then cause other complications. Please contact your web host in case you are not sure how to do this!
Command list
The commands of WP-CLI commands are divided into 2 main categories: bulk processing commands and single processing commands.
Bulk processing commands
We begin first with the bulk processing commands since these are the most commonly used. To access the embedded help for these commands, please execute:
wp help spio bulk
Now let us go through the commands one by one.
Bulk Auto
wp spio bulk auto [--queue=<name>]
This command automatically processes (in bulk) everything that needs to be processed, according to the settings at the time of execution. It is identical to the bulk process of the WP Admin dashboard, with the note that all settings should be checked before executing this command. It is a chain of commands (see below): Create the queue(s), prepare the queue(s) by adding the items to be processed, and then start and run the process. Immediately after executing the command, you will see the main settings and the status of the queue, then the processing will start.
Options
--queue=<name>
Use this parameter to process the Media Library bulk processing queue or the Custom Media bulk processing queue. Omit the parameter to process both of them (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
#Starting the automatic bulk processing $ wp spio bulk auto +----------------------+--------+ | setting | value | +----------------------+--------+ | Compression | Lossy | | Image Backup | Yes | | Processed Thumbnails | Yes | | | | | Creates Webp | Yes | | Creates Avif | Yes | +----------------------+--------+ [Auto Bulk] Starting to process --- Current Status --- +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | queue name | in queue | in process | fatal errors | done | total | preparing | running | finished | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | media | 70 | 0 | 0 | 0 | 70 | No | No | No | | custom | 4 | 0 | 0 | 0 | 4 | No | No | No | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ Start signal for Bulk Processing given. Bulk Running ... (media : test-image-1.jpg) Optimizing - Item has been sent to ShortPixel (0/12) (cycle 0) (media : test-image-2.png) Optimizing - Item has been sent to ShortPixel (0/12) (cycle 0) (custom : custom-image-1.gif) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) (custom : custom-image-2.jpg) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) (custom : custom-image-3.png) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) --------------------------------------- (media : test-image-1-scaled.jpg) Item successfully optimized (cycle 1) +-------------------------------+-------------+ | name | improvement | +-------------------------------+-------------+ | medium | 49.42% | | large | 10.54% | | thumbnail | 60.90% | | medium_large | 18.83% | | 1536x1536 | 2.93% | | 2048x2048 | 0.06% | | post-thumbnail | 3.64% | | twentytwenty-fullscreen | 0.20% | | woocommerce_thumbnail | 25.38% | | woocommerce_single | 26.13% | | woocommerce_gallery_thumbnail | 70.98% | | shop_catalog | 25.38% | | shop_single | 26.13% | | shop_thumbnail | 70.98% | | | | | Total | 28% | +-------------------------------+-------------+ This job, 36 credit(s) were used. 12 for images , 12 for webps , 12 for avifs --------------------------------------- Current Status for Total : (1\75) Done (2%), 74 awaiting 0 errors --
Bulk Add
wp spio bulk add <id> [--type=<type>] [--halt]
This command adds a single image to the bulk processing queue(s) and then starts processing the entire bulk queue(s).
Arguments
id
This is the ID of the file from the Media Library or the ID from the Custom Media folders. You can get the Media Library ID by clicking on the appropriate image/file in the Media Library and looking at the URL in the address bar. In this example, 903 is the Media Library ID, which you can use with the above command: https://example.com/wp-admin/post.php?post=903&action=edit
For Custom Media, you can find the ID by going to Media > Custom Media and hovering over the Custom Media item. In this example, 21 is the Custom Media item ID:
Options
--type=<type>
This is the type of media item to add to the queue. It is required when adding Custom Media files. Valid values are media
and custom
. Default is media
. Example: --type=custom
.
--halt
Stop (don't process the queue) after adding the item to the queue.
Example
# Add a single Media Library item to the bulk processing queue $ wp spio bulk add 903 Success: Item added to queue and will be optimized on the next run You can optimize images via the run command --- Current Status --- +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | queue name | in queue | in process | fatal errors | done | total | preparing | running | finished | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | media | 32 | 30 | 2 | 8 | 72 | No | Yes | No | | custom | 0 | 0 | 0 | 4 | 4 | No | No | No | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ Bulk Running ... # Add a single Custom Media item to the bulk processing queue and stop from processing $ wp spio bulk add 8 --type=custom --halt Success: Item added to queue and will be optimized on the next run You can optimize images via the run command --- Current Status --- +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | queue name | in queue | in process | fatal errors | done | total | preparing | running | finished | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | media | 32 | 30 | 2 | 8 | 72 | No | Yes | No | | custom | 1 | 0 | 0 | 4 | 5 | No | No | No | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+
Bulk Clear
wp spio bulk clear [--queue=<name>]
This command clears the bulk processing queue(s). It's very useful if you find that you want to change some settings and restart the entire bulk process.
Options
--queue=<name>
Use this parameter to clear the Media Library bulk processing queue or the Custom Media bulk processing queue. Omit the parameter to clear both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Clear just the Custom Media bulk processing queue $ wp spio bulk clear --queue=custom Success: Queue(s) cleared # Clear both bulk processing queues $ wp spio bulk clear Success: Queue(s) cleared<br>
Bulk Create
wp spio bulk create [--queue=<name>]
This is the first command in the chain of manual creation and execution of a bulk process. It creates the queue(s) for bulk processing.
Options
--queue=<name>
Use this parameter to create either the Media Library bulk processing queue or the Custom Media bulk processing queue. Omit the parameter to create both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Create both bulk processing queues $ wp spio bulk create Bulk media created. Ready to prepare Bulk custom created. Ready to prepare
Bulk Prepare
wp spio bulk prepare [--queue=<name>]
This is the second command in the chain of manual creation and execution of a bulk process. It prepares the queue(s) for bulk processing by searching for and adding the images that need to be processed. It scans the entire Media Library (and Custom Media folders, if any), checks if there is anything to optimize based on the settings, and then adds those items to the appropriate queue(s).
Options
--queue=<name>
Use this parameter to prepare either the Media Library bulk processing queue or the Custom Media bulk processing queue. Omit the parameter to prepare both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Prepare both bulk processing queues $ wp spio bulk prepare Bulk Preparing is done. 63 items. Use start command to signal ready. Use run to process after starting.
Bulk Start
wp spio bulk start [--queue=<name>]
This is the third command in the chain of manual creation and execution of a bulk process. It simply gives the signal that everything is prepared and ready for processing.
Options
--queue=<name>
Use this parameter to start either the Media Library bulk processing queue or the Custom Media bulk processing queue. Omit the parameter to give the start signal to both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Give the start signal for both queues $ wp spio bulk start Start signal for Bulk Processing given.
Bulk Run
wp spio bulk run [--ticks=<number>] [--wait=<miliseconds>] [--queue=<name>]
This is the last command in the chain of manual creation and execution of a bulk process. It starts processing what has been added to the processing queue(s), and optionally stops after a certain number of "ticks". A tick (or cycle) means a request sent to the API, either to send an image to be processed or to check whether the API has completed processing.
Options
--ticks=<number>
How many times (cycles) the queue will run for. Example: --ticks=3
.
--wait=<miliseconds>
How many milliseconds to wait for the next tick (cycle). Default is 3. Example: --wait=5
.
--queue=<name>
Use this parameter to run either the Media Library bulk processing queue or the Custom Media bulk processing queue. Omit the parameter to run both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Run just the Custom Media queue for 5 cycles $ wp spio bulk run --ticks=5 --queue=custom (custom : custom-image-1.gif) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) (custom : custom-image-2.jpg) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) (custom : custom-image-3.png) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) (custom : custom-image-1.gif) Optimizing - waiting for results (0/1) (cycle 1) (custom : custom-image-2.jpg) Optimizing - waiting for results (0/1) (cycle 1) # Run both queues until everything is done $ wp spio bulk run (media : test-image-3.jpg) Optimizing - Item has been sent to ShortPixel (0/7) (cycle 0) (media : test-image-4.jpg) Optimizing - Item has been sent to ShortPixel (0/9) (cycle 0) --------------------------------------- (custom : custom-image-1.gif) Item successfully optimized (cycle 2) +-------+-------------+ | name | improvement | +-------+-------------+ | main | 10.15% | | | | | Total | 10% | +-------+-------------+ This job, 3 credit(s) were used. 1 for images , 1 for webps , 1 for avifs --------------------------------------- Current Status for Total : (1\63) Done (3%), 62 awaiting 0 errors -- (media : test-image-5.jpg) Optimizing - Item has been sent to ShortPixel (0/3) (cycle 0) (media : test-image-6.jpg) Optimizing - Item has been sent to ShortPixel (0/4) (cycle 0) --------------------------------------- (media : test-image-3.jpg) Item successfully optimized (cycle 1) +-------------------------------+-------------+ | name | improvement | +-------------------------------+-------------+ | main | 0.00% | | medium | 8.41% | | thumbnail | 3.56% | | medium_large | 12.38% | | woocommerce_thumbnail | 9.61% | | woocommerce_single | 12.75% | | woocommerce_gallery_thumbnail | 0.24% | | shop_catalog | 9.61% | | shop_single | 12.75% | | shop_thumbnail | 0.24% | | | | | Total | 7% | +-------------------------------+-------------+ This job, 21 credit(s) were used. 7 for images , 7 for webps , 7 for avifs --------------------------------------- Current Status for Total : (2\63) Done (5%), 61 awaiting 0 errors --
Bulk Status
wp spio bulk status [--show-debug]
This command displays the current status of the bulk processing queues.
Options
--show-debug
Displays more information for debugging purposes.
Example
# Show the current status of the bulk processing queues $ wp spio bulk status --- Current Status --- +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | queue name | in queue | in process | fatal errors | done | total | preparing | running | finished | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | media | 56 | 5 | 0 | 1 | 62 | No | Yes | No | | custom | 0 | 0 | 0 | 1 | 1 | No | No | Yes | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+
Bulk Settings
wp spio bulk settings
This command displays the key settings applied to the bulk processing queues.
Example
# Show the current settings for the bulk processing queues $ wp spio bulk settings +----------------------+--------+ | setting | value | +----------------------+--------+ | Compression | Glossy | | Image Backup | Yes | | Processed Thumbnails | Yes | | | | | Creates Webp | Yes | | Creates Avif | Yes | +----------------------+--------+
Single processing commands
If you would like to view the embedded help for these commands, please run:
wp help spio
Add
wp spio add <id> [--type=<type>] [--halt]
This command adds a single image to the single processing queue(s) and then processes the entire single queue(s).
Arguments
id
This is the ID of the file from the Media Library or the ID from the Custom Media folders. You can get the Media Library ID by clicking on the appropriate image/file in the Media Library and looking at the URL in the address bar. In this example, 903 is the Media Library ID, which you can use with the above command: https://example.com/wp-admin/post.php?post=903&action=edit
For Custom Media, you can find the ID by going to Media > Custom Media and hovering over the Custom Media item. In this example, 21 is the Custom Media item ID:
Options
--type=<type>
This is the type of media item to add to the queue. It is required when adding Custom Media files. Valid values are media
and custom
. Default is media
. Example: --type=custom
.
--halt
Stop (don't process the queue) after adding the item to the queue.
Example
#Add a single Custom Media image to the queue, without processing it $ wp spio add 21 --type=custom --halt Success: Item added to queue and will be optimized on the next run You can optimize images via the run command --- Current Status --- +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | queue name | in queue | in process | fatal errors | done | total | preparing | running | finished | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | media | 0 | 0 | 0 | 0 | 0 | No | No | No | | custom | 1 | 0 | 0 | 0 | 1 | No | No | No | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+
Clear
wp spio clear [--queue=<name>]
This command clears the single processing queue(s). It's very useful if you find that you need to change some settings and restart the process.
Options
--queue=<name>
Use this parameter to clear the Media Library single processing queue or the Custom Media single processing queue. Omit the parameter to clear both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Clear both single processing queues $ wp spio clear Success: Queue(s) cleared
Restore
wp spio restore <id> [--type=<type>]
This command restores a single image from the backups (if they exist) to its original state.
Arguments
id
This is the ID of the file from the Media Library or the ID from the Custom Media folders. You can get the Media Library ID by clicking on the appropriate image/file in the Media Library and looking at the URL in the address bar. In this example, 903 is the Media Library ID, which you can use with the above command: https://example.com/wp-admin/post.php?post=903&action=edit
For Custom Media, you can find the ID by going to Media > Custom Media and hovering over the Custom Media item. In this example, 21 is the Custom Media item ID:
Options
--type=<type>
This is the type of media item to be restored. It is required if you are restoring Custom Media files. Valid values are media
and custom
. Default is media
. Example: --type=media
.
Example
# Restore a Custom Media image $ wp spio restore 21 --type=custom Success: Item restored # Restore a Media Library image $ wp spio restore 903 Success: Item restored
Run
wp spio run [--ticks=<number>] [--wait=<miliseconds>] [--queue=<name>]
This command begins processing the data added to the single processing queue(s), optionally stopping after a specified number of "ticks". A tick (or cycle) means a request sent to the API, either to send an image to be processed or to check whether the API has completed processing.
Options
--ticks=<number>
How many times (cycles) the queue will run for. Example: --ticks=6
.
--wait=<miliseconds>
How many milliseconds to wait for the next tick (cycle). Default is 3. Example: --wait=5
.
--queue=<name>
Use this parameter to run either the Media Library processing queue or the Custom Media processing queue. Omit the parameter to run both (the default). Valid values are media
and custom
. Default is media,custom
. Example: --queue=media
.
Example
# Run just the Custom Media single processing queue when there's nothing to process $ wp spio run --queue=custom (customSingle : test_image_4.jpeg) Optimizing - Item has been sent to ShortPixel (0/1) (cycle 0) --------------------------------------- (customSingle : test_image_4.jpeg) Item successfully optimized (cycle 1) +-------+-------------+ | name | improvement | +-------+-------------+ | main | 41.00% | | | | | Total | 41% | +-------+-------------+ This job, 3 credit(s) were used. 1 for images , 1 for webps , 1 for avifs --------------------------------------- Current Status for Total : (1\1) Done (100%), 0 awaiting 0 errors -- All Queues report processing has finished
Status
wp spio status [--show-debug]
This command displays the current status of each single processing queue.
Options
--show-debug
Displays more information for debugging purposes.
Example
# Show the current status of the single processing queues $ wp spio status --- Current Status --- +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | queue name | in queue | in process | fatal errors | done | total | preparing | running | finished | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+ | media | 0 | 0 | 0 | 0 | 0 | No | No | Yes | | custom | 0 | 0 | 0 | 0 | 0 | No | No | Yes | +------------+----------+------------+--------------+------+-------+-----------+---------+----------+
Settings
wp spio settings
This command displays the key settings applied to each single processing queue.
Example
# Show the current settings for the single processing queues $ wp spio settings +----------------------+-------+ | setting | value | +----------------------+-------+ | Compression | Lossy | | Image Backup | Yes | | Processed Thumbnails | Yes | | | | | Creates Webp | Yes | | Creates Avif | Yes | +----------------------+-------+