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.

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:
  • screen
  • nohup
  • at
• 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.

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 : (175) 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 : (163) 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 : (263) 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]
	

#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       |
+------------+----------+------------+--------------+------+-------+-----------+---------+----------+
	

wp spio clear [--queue=<name>]
	

# Clear both single processing queues 
$ wp spio clear 
Success: Queue(s) cleared
	

wp spio restore <id> [--type=<type>]
	

# 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
	

wp spio run [--ticks=<number>] [--wait=<miliseconds>] [--queue=<name>]
	

# 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 : (11) Done (100%), 0 awaiting 0 errors --
All Queues report processing has finished
	

wp spio status [--show-debug]
	

# 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      |
+------------+----------+------------+--------------+------+-------+-----------+---------+----------+
	

wp spio settings
	

# 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   |
+----------------------+-------+