This article explains how to extract a WP Staging backup on the command line by using the wp-staging-cli tool. If you have issues working on the command line you can use another tool named WP Staging restore tool to do the same job with a graphical user interface.
wp-staging-cli is a powerful, high-performance command-line tool designed to process WP Staging backup files from the command line on each major operating system.
With this tool, users can extract, normalize, and inspect the contents of .wpstg
backup files created by the WP Staging plugin. This standalone extractor is programmed in Go, ensuring exceptional speed and efficiency, and operates independently of WordPress.
Note: The cli tool has been renamed from wpstg-extractor to wp-staging-cli. This article refers to the new name, and you will have to adjust the commands.
The command line tool `wp-staging-cli` is part of the WP Staging Developer and Agency plan and can be downloaded from GitHub.
Key Features
- Extract Backup Files and Database: Access all contents of
.wpstg
backup files. - Database Normalization: Normalize database files within the backup.
- Metadata Dumping: Extract and display metadata from the backup file.
- Index and Header Dumping: Retrieve index and header information from the backup file.
Performance Benchmark
wp-staging-cli is exceptionally fast. For instance, it can extract a 20GB backup in under 36 seconds on an AMD Ryzenโข 7 PRO 7840U with a fast SSD running Ubuntu 22.04.
Installation
Step 1: Download Excutables
- Download the Windows, Linux, and Mac OS executable files from here.
- Extract the zip file and select the appropriate binary for your operating system from the
build
folder. - (Optional) Move the
wp-staging-cli
binary to a directory in yourPATH
for easy access. For example, on Linux:
mv wp-staging-cli /usr/local/bin/
Usage Instructions
To run wp-staging-cli, use the following command:
wp-staging-cli [options] <backupfile.wpstg>
Arguments
<backupfile.wpstg>
: Path to the WP Staging backup file to be processed. This argument is mandatory.
Command options and arguments can be used in any order.
- Options can have a single ‘-‘ or a double ‘–‘ hyphen prefix.
- Options with values can be set with or without ‘=’.
Options
Commands:
extract - Extract items from the backup. Default if no command is specified.
restore - Restore the backup file.
help - Display all help message.
Arguments:
backupfile.wpstg - Path to the WP Staging backup file that will be processed. This argument is mandatory.
General Options:
-l, --license=<licensekey> - WP Staging Pro License Key. Required to access the backup file.
Alternatively, use the `WPSTGPRO_LICENSE` environment variable.
-o, --outputdir=<path> - Specify the extraction directory path where processed files will be stored. Default: "./wp-staging-cli-output".
-n, --normalizedb - Normalize database files during the `extract` process.
This will replace all WP Staging specific placeholders and allows the sql file to be imported by
any regular db admin tool.
--workingdir=<path> - Specify the working directory path where config-related files will be stored. Default: "~/.wp-staging-cli".
--skip-config - Don't reads command options from the configuration file located at "~/.wp-staging-cli/wp-staging-cli.conf".
--siteurl=<siteurl> - Specify a new Site URL.
--db-prefix=<prefix> - Specify a new database table prefix.
--overwrite=<yes|no> - Overwrite the target directory during `extract` and `restore` operations. Default: "yes".
--verify - Verify the integrity of the extracted file.
--yes - Automatically answers "yes" to confirmation prompts.
--confirm-timeout=<num> - Timeout duration (in seconds) for awaiting a "yes" response at confirmation prompts. Default: 30 seconds.
--skip-extract - Don't extract files and use previously extracted and existing files for `restore` process.
For use case, when restore failed, the process can be continued without first extracting all files again.
-or, --only-wproot - Process only the 'wp root' item in the backup.
-ow, --only-wpcontent - Process only the 'wp-content' item in the backup.
-op, --only-plugins - Process only the 'plugins' item in the backup.
-ot, --only-themes - Process only the 'themes' item in the backup.
-om, --only-muplugins - Process only the 'mu-plugins' item in the backup.
-ou, --only-uploads - Process only the 'uploads' item in the backup.
-ol, --only-languages - Process only the 'languages' item in the backup.
-od, --only-dbfile - Process only the database file in the backup.
-oe, --only-dropins - Process only the dropins file in the backup.
-of, --only-file=<string> - Process only items that match the specified string.
-sr, --skip-wproot - Skip processing the 'wp root' item in the backup.
-sw, --skip-wpcontent - Skip processing the 'wp-content' item in the backup.
-sp, --skip-plugins - Skip processing the 'plugins' item in the backup.
-st, --skip-themes - Skip processing the 'themes' item in the backup.
-sm, --skip-muplugins - Skip processing the 'mu-plugins' item in the backup.
-su, --skip-uploads - Skip processing the 'uploads' item in the backup.
-sl, --skip-languages - Skip processing the 'languages' item in the backup.
-sd, --skip-dbfile - Skip processing the database file in the backup.
-se, --skip-dropins - Skip processing the dropins file in the backup.
-sf, --skip-file=<string> - Skip processing items that match the specified string.
-dm, --dump-metadata - Display backup metadata from the backup file.
-di, --dump-index=<data> - Display backup index from the backup file. Use 'data' to show additional information.
-dh, --dump-header - Display backup header from the backup file.
-do, --dump-options - Display the command options that have been parsed.
-d, --debug - Display debug message.
-q, --quiet - Suppress output of processed backup items.
-v, --version - Display version information.
-h, --help - Display all help message.
Restore Options:
-p, --path=<path> - Specify the WordPress root path for restoration. Default: "./".
-wd, --overwrite-db=<yes|no> - Remove database tables not present in the backup. Default: "yes".
-wr, --overwrite-wproot=<yes|no> - Remove files in the WordPress root path that are not in the backup or part of WordPress core. Default: "no".
--db-innodb-strict-mode - Enable InnoDB strict mode if needed. By default, it is turned off during database restoration.
--db-file=<file> - Use the extracted backup SQL file to resume database restoration in case of failure.
--db-insert-batch-size=<num> - Number of queries to batch in a single insert operation. Default: 1000.
--db-insert-multi=<yes|no> - Use multi-row INSERT statements per query to improve performance. Default "yes".
Restore DB Options:
This option overrides the DB-related configuration parsed from the wp-config.php file.
--db-host=<string> - Database Host.
--db-name=<string> - Database Name.
--db-user=<string> - Database User.
--db-pass=<string> - Database Password.
--db-socket=<file> - MySQL socket file path.
--db-charset=<string> - Database charset.
--db-collate=<string> - Database collate.
--db-ssl-ca-cert=<file> - SSL CA file path.
--db-ssl-cert=<file> - SSL certificate file path.
--db-ssl-key=<file> - SSL key file path.
--db-ssl-mode=<mode> - Connects to the database with SSL mode "skip-verify" or "preferred". Default: "skip-verify".
Examples:
wp-staging-cli --license=WPSTGPRO_LICENSE --outputdir=./wpstgbackup backup.wpstg
wp-staging-cli --license=WPSTGPRO_LICENSE --normalizedb --dbprefix=newprefix --siteurl=https://example.com backup.wpstg
With short options:
wp-staging-cli -l WPSTGPRO_LICENSE -o ./wpstgbackup backup.wpstg
wp-staging-cli -l WPSTGPRO_LICENSE -n -dp newprefix -su https://example.com backup.wpstg
Setting the License Key via Environment Variable
The standalone extractor requires an active WP Staging Pro license. (Agency or Developer Plan)
For convenience, you can set the license key using an environment variable:
On Unix-based systems:
export WPSTGPRO_LICENSE=WPSTGPRO_LICENSE_KEY
At Windows command prompt:
set WPSTGPRO_LICENSE=WPSTGPRO_LICENSE_KEY
Contributing to wp-staging-cli
We welcome contributions to wp-staging-cli! If you have suggestions, bug reports, or want to contribute code, open an issue on the GitHub repository.
Related Articles
- WordPress Has No Database Table Prefix. How to Fix it.
- How to use WP Staging | Restore. A Standalone WordPress Installer and Backup Restore Tool
- Update WordPress Core Manually if Automatic Update Does Not Work
- How to Disable WordPress Cron Jobs (on a Staging Site)
- How To Resolve The WordPress Failed To Open Stream Error?