wpstg-cli-faq

wpstg-cli-faq.md

WP-Staging-CLI FAQ

General Questions

Q1: What is wp-staging-cli?
A1: wp-staging-cli is a high-performance command-line tool to process WP Staging backup files (.wpstg). It allows you to extract, normalize, inspect, and restore backups without using WordPress itself.

Q2: Which operating systems are supported?
A2: Windows, Linux, and macOS. Pre-built binaries are available for all major OSes.

Q3: Do I need a license to use this tool?
A3: Yes. You need a valid WP Staging Agency or Developer license key to access backup files.

Q4: How fast is it?
A4: Benchmarks show it can extract a 20GB backup in under 36 seconds on an AMD Ryzen 7 PRO 7840U with a fast SSD running Ubuntu 20.04.

Installation Questions

Q5: How do I install wp-staging-cli?
A5:

1. Download the pre-built binaries from here.
2. Extract the zip file and select the binary for your OS.
3. (Optional) Move it to a folder in your PATH for easier access:

   mv wp-staging-cli /usr/local/bin/

Q6: Can I use it without installing?
A6: Yes, you can run the binary directly from the extracted folder.

Usage Questions

Q7: How do I run wp-staging-cli?
A7: Use the following command:

wp-staging-cli [commands] [options] <backupfile.wpstg>

Commands must come first. Options and the backup file can appear in any order.

Q8: What are the main commands?
A8:

• extract (default) – Extract backup files.
• restore – Restore WordPress site from backup.
• dockerize – Setup a staging site using Docker.
• dump-header – Display backup header info.
• dump-metadata – Display backup metadata.
• dump-index – Display backup index info (--data for detailed output).
• help – Show help message.

Q9: How do I specify my license key?
A9: Either use --license=<licensekey> or set the environment variable WPSTGPRO_LICENSE. Unix:

export WPSTGPRO_LICENSE=YOUR_LICENSE_KEY

Windows CMD:

set WPSTGPRO_LICENSE=YOUR_LICENSE_KEY

Q10: How can I extract and normalize the database file?
A10:

wp-staging-cli extract --license=YOUR_LICENSE_KEY --normalizedb backupfile.wpstg

Q11: How can I restore to a different WordPress path?
A11: Use the --path option:

wp-staging-cli restore --license=YOUR_LICENSE_KEY --path=/var/www/site backupfile.wpstg

If running from the WP root, --path is optional.

Filter Options Questions

Q12: Can I extract only specific parts of the backup?
A12: Yes, using “Only-Filters”:

• --only-wpcontent – Only extract wp-content.
• --only-plugins – Only extract plugins.
• --only-file=<string> – Extract only matching files.

Q13: Can I skip certain parts?
A13: Yes, using “Skip-Filters”:

• --skip-wpcontent – Skip wp-content.
• --skip-uploads – Skip uploads.
• --skip-file=<string> – Skip files matching a string.

Restore Options Questions

Q14: How do I restore to an external database?
A14: Use DB-related options:

wp-staging-cli restore --license=YOUR_LICENSE_KEY --path=/var/www/site \
  --db-name=dbname --db-user=user --db-pass=pass --db-host=host backupfile.wpstg

Q15: Can I overwrite existing files or DB tables?
A15: Yes, use:

• --overwrite=<yes|no> – Overwrite target directory.
• --overwrite-db=<yes|no> – Remove DB tables not in backup.
• --overwrite-wproot=<yes|no> – Remove WP root files not in backup or core.

Config File Questions

Q23: What is the default configuration file used for?
A23: The config file (~/.wp-staging-cli/wp-staging-cli.conf) is used to store default options only, not commands. It allows you to avoid repeatedly typing commonly used options, such as license key, paths, database credentials, filters, or Docker options.

Q24: Can I skip reading the config file?
A24: Yes, use the --skip-config option when running any command. This ensures the CLI ignores the config file entirely and only uses options provided on the command line.

Q25: Do CLI options override the config file?
A25: Yes. Any option provided directly in the CLI command will override the corresponding value in the config file.

Q26: What kind of options can I define in the config file?
A26: You can define most CLI options including:

• License key (license)
• WordPress path (path)
• Database credentials (db-name, db-user, db-pass, db-host)
• File overwrite settings (overwrite, overwrite-db, overwrite-wproot)
• Filters (only-wpcontent, skip-uploads, only-plugins, etc.)
• Docker defaults (php-version, nginx-http-port, mariadb-port, dockerize-path, etc.)
• General options (debug, quiet, verify)

Q27: Can I use multiple config files?
A27: WP-Staging-CLI only reads one config file at a time. By default, it uses ~/.wp-staging-cli/wp-staging-cli.conf, but you can override it with a custom file using --config=file.conf. You can also temporarily bypass it using --skip-config and pass all options directly on the CLI.

Dockerize Questions

Q16: Where is the Docker environment setup?
A16: By default, Docker-related files are stored in ~/wp-staging-cli-dockerize. You can change this location with the --dockerize-path=<path> option.

Q17: How do I specify the docker-compose.yml file for Dockerize?
A17: Use --compose-file=<file> to point to a custom docker-compose.yml. Default is ~/wp-staging-cli-dockerize/docker-compose.yml.

Q18: How can I assign a static IP to Docker services?
A18: Use --container-ip=<ipv4>. Default is 172.17.0.1.

Q19: How can I configure PHP version or ports for Dockerize?
A19: Use --php-version=<version>, --nginx-http-port=<port>, and --nginx-https-port=<port> options. Defaults are 8.1, 80, and 443 respectively.

Q20: How do I configure MariaDB for Dockerize?
A20: You can set --mariadb-port=<port> (default 3306) and --mariadb-root=<string> for root password (default 123456). You can also disable the container with --disable-mariadb.

Q21: How do I configure WordPress in Dockerize?
A21: By default, when you run the setup command, WordPress will be installed with the default site URL https://wpstg-dockerize.local.
If you use the site-add command, only --wp-site-url is mandatory — all other options will fall back to their defaults. If a site is already installed, you can use --wp-reset to perform a fresh installation.
You can further customize the installation with options like --wp-version, --wp-db-host, --wp-db-name, --wp-db-user, --wp-db-pass, --wp-db-prefix, --wp-db-ssl, --wp-admin-user, --wp-admin-pass, --wp-admin-email, and --wp-multiste.

Q22: How do I disable Mailpit container in Dockerize?
A22: Use --disable-mailpit to prevent the Mailpit container from running.

Debugging & Misc

Q28: How do I enable debug messages?
A28: Use -d or --debug.

Q29: Can I suppress output?
A29: Yes, use -q or --quiet.

Q30: How do I verify the integrity of extracted files?
A30: Use the --verify option.

Hi @nawawi ,
Thank you for putting together such a detailed FAQ. It’s incredibly helpful!

I had a quick question for clarification: when using the --only-file or --skip-file options in wp-staging-cli, does the tool support wildcards or regex for matching file patterns (e.g. .log or uploads/), or is it purely substring-based matching?

Thanks again for the great work on this!

It does not support wildcards (*) or regex (/. *? /) , only matches input in filenames. For example "test" will match any filename that has test in it.

Yes, it is substring based matching.