WP-CLI Support

WP Rollback Pro includes full WP-CLI support, giving developers and agencies a first-class terminal interface for listing available versions and executing rollbacks — including Plugin Vault versions and local backups — without touching the WordPress admin.

Pro Feature

WP-CLI commands are available exclusively in WP Rollback Pro. An active license is required. See Licensing for details.

Prerequisites

• WP-CLI v2.0 or later installed and accessible as wp
• WP Rollback Pro installed and activated with a valid license
• A WordPress user to run commands as, passed with --user (recommended). Use one with the update_plugins capability for plugin commands or update_themes for theme commands. See Running as a specific user.

Command Reference

WP Rollback Pro registers two command groups under the wp rollback namespace:

Command group	Targets
wp rollback plugin	Installed plugins
wp rollback theme	Installed themes

Each group exposes two subcommands: list and run.

---

wp rollback plugin list <slug>

List all available versions for an installed plugin.

wp rollback plugin list <slug> [--format=<format>]

Arguments

Argument	Required	Description
<slug>	Yes	The plugin slug (e.g. woocommerce, gravity-forms)
--format	No	Output format: table (default), json, csv, yaml

Examples

# List versions in a table
wp rollback plugin list woocommerce

# Output as JSON for scripting
wp rollback plugin list woocommerce --format=json

# Pipe CSV output for spreadsheet import
wp rollback plugin list woocommerce --format=csv

Sample table output

A WordPress.org plugin such as WooCommerce lists WordPress.org versions only (output shortened):

+---------+---------------+----------+---------+
| version | source        | released | current |
+---------+---------------+----------+---------+
| 9.2.0   | wordpress.org | —        |         |
| 9.1.0   | wordpress.org | —        |         |
| 9.0.0   | wordpress.org | —        |         |
| 8.4.0   | wordpress.org | —        | *       |
| 8.3.0   | wordpress.org | —        |         |
+---------+---------------+----------+---------+

A premium plugin (here a made-up acme-premium) lists local backups and, when the Plugin Vault is connected, Vault versions:

+---------+--------+------------+---------+
| version | source | released   | current |
+---------+--------+------------+---------+
| 2.4.0   | local  | —          | *       |
| 2.3.1   | vault  | 2024-11-05 |         |
| 2.3.0   | local  | —          |         |
| 2.2.0   | vault  | 2024-09-18 |         |
+---------+--------+------------+---------+

The source column indicates where each version comes from:

Source	Description
wordpress.org	Available from the WordPress.org repository
vault	Available in Plugin Vault (premium plugins and themes only)
local	Backed up locally on this server by WP Rollback Pro (premium plugins and themes only)

For a premium plugin or theme, the installed version (marked *) can show as local even when no backup of it exists yet.

---

wp rollback theme list <slug>

List all available versions for an installed theme.

wp rollback theme list <slug> [--format=<format>]

Usage is identical to wp rollback plugin list. Replace the slug with your theme's directory name.

wp rollback theme list astra
wp rollback theme list astra --format=json

---

wp rollback plugin run <slug> <version>

Roll back an installed plugin to a specific version.

wp rollback plugin run <slug> <version> [--force]

Arguments

Argument	Required	Description
<slug>	Yes	The plugin slug
<version>	Yes	The target version string (e.g. 8.4.0)
--force	No	Skip the interactive confirmation prompt

What happens during a run

The command executes the complete WP Rollback Pro pipeline — the same steps triggered by the admin UI:

1. Maintenance mode — puts the site in maintenance mode to protect visitors
2. Download asset — fetches the target version (a local backup first, then Plugin Vault, then WordPress.org)
3. Verify asset — confirms the SHA-256 checksum of the downloaded file before anything opens it (Plugin Vault downloads only) (Pro)
4. Backup current version — creates a local backup of the currently-installed files
5. Validate package — verifies the ZIP structure (Pro)
6. Replace asset — swaps the files on disk and turns maintenance mode off
7. Cleanup — removes temporary files

If any step fails, including with a PHP error, the command turns maintenance mode off before it exits.

Examples

# Interactive rollback with confirmation prompt
wp rollback plugin run woocommerce 8.4.0

# Skip confirmation (useful in deployment scripts)
wp rollback plugin run woocommerce 8.4.0 --force

# Run as a specific WordPress user
wp rollback plugin run woocommerce 8.4.0 --force --user=admin

Sample output

Roll back plugin "woocommerce" to version 8.4.0? [y/n] y
Rolling back "woocommerce" to 8.4.0  100% [====================================] 0:00 / 0:00
  — Enabling maintenance mode…
  — Download requested version…
  — Creating version archive…
  — Validating package integrity…
  — Verifying package integrity…
  — Replacing files…
  — Cleaning up temporary files…
Success: Successfully rolled back plugin "woocommerce" to version 8.4.0.

---

wp rollback theme run <slug> <version>

Roll back an installed theme to a specific version.

wp rollback theme run <slug> <version> [--force]

Usage is identical to wp rollback plugin run.

wp rollback theme run astra 3.9.0
wp rollback theme run astra 3.9.0 --force

---

Running as a Specific User

WP-CLI can run as any WordPress user via the global --user flag. Use a user with the update_plugins capability for plugin commands or update_themes for theme commands. list checks this capability before it shows versions.

# Run as user with ID 1
wp rollback plugin run woocommerce 8.4.0 --user=1

# Run as a user by login
wp rollback plugin run woocommerce 8.4.0 --user=admin

We recommend passing --user to run. WP Rollback Pro records the rollback under that user, so the Dashboard's Rollback history shows who ran it. Without --user, the rollback still runs but is recorded with no user, and the history shows it as "System Update".

When --user is omitted, list temporarily switches to the first administrator account so it can look up versions. run doesn't switch users.

Using in Deployment Scripts

The --force flag makes the run command fully non-interactive, which is ideal for CI/CD pipelines, staging deployments, or automated recovery workflows.

#!/bin/bash
# Roll back woocommerce and exit with the WP-CLI status code
wp rollback plugin run woocommerce 8.4.0 --force --user=admin
echo "Rollback exited with status $?"

WP-CLI exits with code 0 on success and a non-zero code on failure, so you can use standard shell error handling:

wp rollback plugin run woocommerce 8.4.0 --force --user=admin || {
  echo "Rollback failed — check WP-CLI output above"
  exit 1
}

Plugin Vault in the CLI

When you run wp rollback plugin list <slug> for a premium plugin, versions sourced from Plugin Vault are shown with source: vault. The run command uses a local backup of that version first if the site has one, and Plugin Vault otherwise.

Vault Licence Requirement

You must hold a valid, active licence for any plugin or theme you roll back via Plugin Vault — the same requirement as the admin UI. See Plugin Vault for full details.

Vault authentication happens automatically using your stored JWT token. If the token has expired, WP Rollback Pro will silently re-authenticate via your active Pro licence before proceeding.

Troubleshooting

"Could not find installed plugin." on list

The slug doesn't match an installed plugin (for themes, the message is "Could not find installed theme."). Use the folder name shown in the name column of:

wp plugin list --fields=name,title,status
wp theme list --fields=name,title,status

"Rollback failed: …" during run

Check the error message displayed after the failing step. Common causes:

• The target version is not available from any source (Vault, local, or WordPress.org)
• Insufficient filesystem permissions to replace plugin files
• SHA-256 verification failed — the downloaded ZIP may be corrupted
• A PHP error in one of the steps. The message shows the error, and the file path shows which plugin or theme it came from.

WP Rollback turns maintenance mode off when a step fails. If a rollback is interrupted some other way (for example, the server kills the process), the maintenance page turns itself off after 10 minutes. To clear it right away, delete the .wpr-maintenance file in the WordPress root folder:

wp eval "@unlink( ABSPATH . '.wpr-maintenance' );"

wp maintenance-mode deactivate won't clear it. That command controls WordPress core's own maintenance mode, which WP Rollback doesn't use.

Vault versions not appearing in list

Ensure your WP Rollback Pro licence is active and the site has successfully authenticated with Plugin Vault. To check, open Settings → Pro License in WP Rollback Pro and confirm the license is active and registered to this site. Vault versions only appear for premium plugins and themes.