{"id":36617227,"url":"https://github.com/wp-staging/wp-staging-cli-release","last_synced_at":"2026-01-16T18:29:10.339Z","repository":{"id":248371991,"uuid":"828509333","full_name":"wp-staging/wp-staging-cli-release","owner":"wp-staging","description":"Create local Docker compatible containers and extract WP Staging backups at native speed, straight from the command line. These cross platform binaries are built for pros who want a clean, reliable workflow on Windows, Linux, or macOS. Requires a valid, active WP Staging Pro license.","archived":false,"fork":false,"pushed_at":"2026-01-12T13:05:59.000Z","size":160447,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-12T16:56:09.925Z","etag":null,"topics":["backup","backup-tool","development","modern-web","staging","staging-environment","wordpress-development"],"latest_commit_sha":null,"homepage":"https://wp-staging.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wp-staging.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-14T11:21:34.000Z","updated_at":"2026-01-12T12:05:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"d4209893-f790-4c51-86a6-76de62398f97","html_url":"https://github.com/wp-staging/wp-staging-cli-release","commit_stats":null,"previous_names":["wp-staging/wpstg-extractor-releases","wp-staging/wp-staging-cli-releases","wp-staging/wp-staging-cli-release"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/wp-staging/wp-staging-cli-release","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-staging%2Fwp-staging-cli-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-staging%2Fwp-staging-cli-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-staging%2Fwp-staging-cli-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-staging%2Fwp-staging-cli-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wp-staging","download_url":"https://codeload.github.com/wp-staging/wp-staging-cli-release/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-staging%2Fwp-staging-cli-release/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28480815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","backup-tool","development","modern-web","staging","staging-environment","wordpress-development"],"created_at":"2026-01-12T09:13:57.072Z","updated_at":"2026-01-16T18:29:10.312Z","avatar_url":"https://github.com/wp-staging.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WP Staging CLI\n\n**WP Staging CLI** is a high-performance, cross-platform command-line tool for processing **WP Staging** backup files (`.wpstg`).\nIt allows you to extract, normalize, inspect, and restore backups created by the [WP Staging Pro](https://wp-staging.com) plugin — even when your WordPress site is broken or inaccessible — and spin up isolated test environments using Docker containers.\n\nThis tool is designed for developers and system administrators who want to automate WordPress site cloning, migration, and environment setup.\n\n\u003e License Required:  \n\u003e You must have a valid [WP Staging Agency or Developer license key](https://wp-staging.com) to use this tool.\n\n---\n\n## Highlights\n\n- **Dockerized Development Environments** — Spin up isolated WordPress environments with Docker Compose, including PHP-FPM, Nginx, MariaDB, and Mailpit.\n- **Offline Backup Restoration** — Restore WordPress sites and databases even when the original installation is broken or inaccessible.\n- **Stream-Based Extraction** — Memory-efficient extraction of large `.wpstg` backup files using chunked processing.\n- **Database Normalization** — Automatically process WP Staging placeholders (`{WPSTG_TMP_PREFIX}`, `{WPSTG_FINAL_PREFIX}`, etc.) for standard SQL import.\n- **Backup Introspection** — Inspect backup headers, metadata, and file indexes without full extraction.\n- **Cross-Platform Support** — Native binaries for Linux, Windows, and macOS with platform-specific optimizations.\n---\n\n## Benchmarks\n\n**Speed:** Extracted a 20 GB backup file in just 36 seconds on a modern computer with SSD storage.\n\n---\n\n## Installation\n\n### Quick Install (Recommended)\n\n**Linux / macOS / WSL:**\n```bash\ncurl -fsSL https://wp-staging.com/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://wp-staging.com/install.ps1 | iex\n```\n\n**Windows (CMD):**\n```cmd\ncurl -fsSL https://wp-staging.com/install.cmd -o install.cmd \u0026\u0026 install.cmd \u0026\u0026 del install.cmd\n```\n\nThe installer will:\n- Download the latest version for your platform\n- Verify checksums for security\n- Install to `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\\Programs\\wpstaging` (Windows)\n- Add to your PATH automatically\n- Install bash completion (Linux/macOS)\n\n### Install a Specific Version (including Beta/RC)\n\nBy default, the installer downloads the latest stable release. To install a specific version (including beta, alpha, or release candidate versions):\n\n**Linux / macOS / WSL:**\n```bash\ncurl -fsSL https://wp-staging.com/install.sh | bash -s -- -v 1.4.3-beta.1\n```\n\n**Windows (PowerShell):**\n```powershell\n\u0026 ([scriptblock]::Create((irm https://wp-staging.com/install.ps1))) -v \"1.4.3-beta.1\"\n```\n\n**Windows (CMD):**\n```cmd\ncurl -fsSL https://wp-staging.com/install.cmd -o install.cmd \u0026\u0026 install.cmd -v 1.4.3-beta.1 \u0026\u0026 del install.cmd\n```\n\n**Available versions**: See all releases at [GitHub Releases](https://github.com/wp-staging/wp-staging-cli-release/tags)\n\n### Manual Installation\n\nIf you prefer to download and install manually:\n\n1. Download the latest release archive from:\n   [GitHub Releases (main.zip)](https://github.com/wp-staging/wp-staging-cli-release/archive/refs/heads/main.zip)\n2. Extract the archive and locate the binary in the `build` folder for your platform:\n   - **Linux**: `build/linux_amd64/wpstaging` (64-bit) or `build/linux_i386/wpstaging` (32-bit)\n   - **macOS**: `build/macos_arm64/wpstaging` (Apple Silicon) or `build/macos_amd64/wpstaging` (Intel)\n   - **Windows**: `build/windows_amd64/wpstaging.exe` (64-bit) or `build/windows_i386/wpstaging.exe` (32-bit)\n3. Make it accessible from anywhere on your computer:\n\n**Linux / macOS:**\n```bash\n# User installation (no sudo required)\nmkdir -p ~/.local/bin\nmv wpstaging ~/.local/bin/\nchmod +x ~/.local/bin/wpstaging\n\n# Or system-wide installation\nsudo mv wpstaging /usr/local/bin/\nsudo chmod +x /usr/local/bin/wpstaging\n```\n\n**Windows:**\n1. Create a directory: `C:\\Program Files\\wpstaging\\`\n2. Move `wpstaging.exe` to that directory\n3. Add `C:\\Program Files\\wpstaging\\` to your PATH environment variable\n\n### Uninstallation\n\n**Remove Docker Environment (Optional):**\n\nIf you've used the dockerize features, first remove all Docker containers and data:\n\n```bash\nwpstaging uninstall\n```\n\nThis will stop and remove all Docker containers, volumes, and configurations.\n\n#### Quick Uninstall (Recommended)\n\n**Linux / macOS / WSL:**\n```bash\ncurl -fsSL https://wp-staging.com/uninstall.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://wp-staging.com/uninstall.ps1 | iex\n```\n\n**Windows (CMD):**\n```cmd\ncurl -fsSL https://wp-staging.com/uninstall.cmd -o uninstall.cmd \u0026\u0026 uninstall.cmd \u0026\u0026 del uninstall.cmd\n```\n\nThe uninstaller will:\n- Remove the wpstaging binary and aliases\n- Remove PATH entries\n- Remove license key environment variable\n- Remove cache directories\n\n#### Manual Uninstallation\n\nIf you prefer to uninstall manually:\n\n**Linux / macOS:**\n```bash\n# Remove binary\nrm ~/.local/bin/wpstaging  # or: sudo rm /usr/local/bin/wpstaging\n\n# Remove bash completion (if installed)\nrm ~/.local/share/bash-completion/completions/wpstaging\n\n# Remove license and cache data\nrm -rf ~/.wpstaging\n```\n\n**Windows (PowerShell):**\n```powershell\n# Remove binary\nRemove-Item \"$env:LOCALAPPDATA\\Programs\\wpstaging\" -Recurse -Force\n\n# Remove from PATH (manual step required)\n# Go to System Properties \u003e Environment Variables \u003e User Variables \u003e PATH\n# Remove the wpstaging entry\n\n# Remove license and cache data\nRemove-Item \"$env:USERPROFILE\\.wpstaging\" -Recurse -Force\n```\n\n---\n\n## Usage\n\n```bash\nwpstaging [command] [flags] \u003cbackupfile.wpstg\u003e\n```\n\n- Commands must come first\n- Flags and `\u003cbackupfile.wpstg\u003e` can appear in any order\n\n### Commands\n\nBelow are the available commands you can use. The tool is organized into groups to make it easy to work with backups, manage Docker environments, and handle WordPress sites.\n\n**Site Commands:**\n\nThese commands help you manage multiple WordPress sites in your Docker environment.\n\n| Command | Description |\n|----------|-------------|\n| `add` | Add a new WordPress site |\n| `list` | List all sites or show details for a specific site |\n| `del` | Delete a WordPress site |\n| `enable` | Enable a WordPress site |\n| `disable` | Disable a WordPress site |\n| `reset` | Reset a WordPress site |\n\n**Backup Commands:**\n\nThese commands help you work with WP Staging backup files to extract, restore, and inspect their contents.\n\n| Command | Description |\n|----------|-------------|\n| `extract` | Extract files, database, or metadata from a WP STAGING backup |\n| `restore` | Restore a WordPress site from a WP STAGING backup |\n| `dump-header` | View backup header details |\n| `dump-metadata` | View metadata from a backup file |\n| `dump-index` | View backup index details |\n\n**Docker Commands:**\n\nThese commands help you control Docker containers for your WordPress environment.\n\n| Command | Description |\n|----------|-------------|\n| `start` | Start containers for a site or all sites |\n| `stop` | Stop containers for a site or all sites |\n| `restart` | Restart containers for a site or all sites |\n| `status` | Display container status for a site or all sites |\n| `shell` | Open an interactive shell in the PHP container |\n| `uninstall` | Stop containers and remove all Docker data |\n| `update-hosts-file` | Update the local hosts file with site entries |\n| `generate-compose-file` | Generate a docker-compose.yml file |\n| `generate-docker-file` | Generate Docker configuration files |\n\n**Other Commands:**\n\nThese commands help you manage your license and cache.\n\n| Command | Description |\n|----------|-------------|\n| `register` | Activate your WP Staging Pro license |\n| `clean` | Clean up cached data, license info, and temporary files |\n| `help` | Help about any command |\n\n### Your Backup File\n`backupfile.wpstg` — The backup file you want to work with. You'll need this for `extract` and `restore` commands.\n\n### Flags\nSee [WP Staging CLI Command Reference](./docs/COMMANDS.md) for a full list of available flags.\n\n---\n\n## Examples\n\n### Extract a Backup\n\nExtract all files and database from your backup to the default output directory.\n\n```bash\nwpstaging extract backupfile.wpstg\n```\n\n### Extract from Remote URL\n\nExtract a backup directly from a remote URL without downloading it manually first.\n\n```bash\n# Using --from flag\nwpstaging extract --from=https://example.com/backups/backup.wpstg\n\n# Or pass URL directly as argument\nwpstaging extract https://example.com/backups/backup.wpstg\n```\n\nThe CLI will:\n1. Validate the remote file (size and format)\n2. Display backup information\n3. Ask for confirmation before downloading\n4. Download with progress indicator (supports resume for interrupted downloads)\n\n### Extract and Prepare Database for Import\n\nExtract your backup and automatically clean up the database file so it's ready to import with standard database tools.\n\n```bash\nwpstaging extract --normalizedb backupfile.wpstg\n```\n\n### Extract and Replace URL \u0026 Prefix\n\nExtract your backup while replacing the site URL and database prefix. Perfect for moving your site to a new domain or environment.\n\n```bash\nwpstaging extract --normalizedb \\\n  --siteurl=https://example.local --db-prefix=wpsite backupfile.wpstg\n```\n\n---\n\n### Restore to a Specific Directory\n\nRestore your entire WordPress site (files and database) to a specific directory on your server.\n\n```bash\nwpstaging restore --path=/var/www/site backupfile.wpstg\n```\n\nOr, if you're already inside the WordPress root directory:\n```bash\ncd /var/www/site\nwpstaging restore backupfile.wpstg\n```\n\n### Restore from Remote URL\n\nRestore a WordPress site directly from a remote backup URL.\n\n```bash\nwpstaging restore --path=/var/www/site --from=https://example.com/backups/backup.wpstg\n```\n\n### Restore to External Database\n\nRestore your site while connecting to an external or remote database server. Useful when your database is hosted separately.\n\n```bash\nwpstaging restore --path=/var/www/site \\\n  --db-name=dbname --db-user=user --db-pass=pass --db-host=host backupfile.wpstg\n```\n\n---\n\n### Dump Backup Index\n\nSee what's inside your backup file before extracting it. This shows you all the files included in the backup.\n\n**Basic:**\n```bash\nwpstaging dump-index backupfile.wpstg\n```\n\n**Detailed output:**\n```bash\nwpstaging dump-index --data backupfile.wpstg\n```\n\n---\n\n### Dockerize WordPress\n\nCreate isolated Docker-based WordPress environments for testing and development.\n\n**Add a new site:**\n\nCreate a new WordPress site with a custom local domain.\n\n```bash\nwpstaging add https://mysite.local\n```\n\n**Start containers:**\n\nStart your Docker environment after adding sites or after stopping it.\n\n```bash\nwpstaging start\nwpstaging start mysite.local  # Start a specific site only\n```\n\n**Manage WordPress sites:**\n\nAdd, list, reset, or remove WordPress sites in your Docker environment.\n\n```bash\nwpstaging add https://newsite.local\nwpstaging list\nwpstaging list site1.local site2.local  # Show details for multiple sites\nwpstaging reset mysite.local  # Reset site to fresh WordPress\nwpstaging del oldsite.local\nwpstaging del site1.local site2.local  # Delete multiple sites\nwpstaging del  # Delete all sites (with confirmation)\n```\n\n**Access the staging site:**\n\nOnce running, visit your site in a browser.\n\n```text\nhttps://mysite.local\n```\n\n**Important Notes:**\n\n- **Linux/macOS:** Some operations may ask for your password (sudo) to update your hosts file. This is normal and only happens during initial setup.\n- **macOS Users (Passwordless Sudo Recommended):** Automatic IP alias binding is enabled by default for seamless multi-site setups using loopback IP range **127.3.2.1 - 127.3.2.254**. This requires sudo and you'll be prompted for your password in each new terminal session (5-15 minute timeout per session). **Solution:** Set up passwordless sudo for wpstaging — see [FAQ Q76](./docs/FAQ.md#q76-how-do-i-set-up-passwordless-sudo-for-wpstaging-cli) for step-by-step instructions. Alternatively, use `--skip-macos-auto-ip` to disable automatic IP binding (requires manual `ifconfig lo0 alias` commands for each IP in the range).\n- **External Service Conflicts:** If other services (Apache, nginx, MySQL) are using ports on the wpstaging IP range, the CLI detects this and either auto-switches to the next available IP (for new sites) or shows clear error messages with diagnostic commands.\n- **Skip hosts update:** If you prefer to manage your hosts file manually, use `--skip-update-hosts-file` when creating sites.\n\n---\n\n### Register Your License (Recommended)\n\nRun the `register` command once to securely save your license:\n\n```bash\n# Interactive mode (prompts for license key)\nwpstaging register\n\n# Non-interactive mode (useful for scripts/automation)\nwpstaging register --license=YOUR_LICENSE_KEY\n```\n\nYour license key is encrypted and validated. After registration, you can run any command without the `--license` flag.\n\n**Alternative Methods for Automation:**\n\n- **Environment variable** `WPSTGPRO_LICENSE`:\n  - Unix/macOS: `export WPSTGPRO_LICENSE=YOUR_LICENSE_KEY`\n  - Windows CMD: `set WPSTGPRO_LICENSE=YOUR_LICENSE_KEY`\n  - Windows PowerShell: `$env:WPSTGPRO_LICENSE=\"YOUR_LICENSE_KEY\"`\n\n- **Per-command flag**: `--license=YOUR_LICENSE_KEY` (on extract/restore commands)\n\n### Environment Variables\n\n| Variable | Purpose | Example |\n|----------|---------|---------|\n| `WPSTGPRO_LICENSE` | License key | `export WPSTGPRO_LICENSE=abc123...` |\n| `WPSTGCLI_DEBUG` | Enable debug output | `export WPSTGCLI_DEBUG=1` |\n| `WPSTGCLI_QUIET` | Suppress informational output | `export WPSTGCLI_QUIET=1` |\n| `WPSTGCLI_ALLOW_ROOT` | Allow running as root user | `export WPSTGCLI_ALLOW_ROOT=1` |\n\n---\n\n### Use a Config File\n\nYou can create a settings file to remember your preferences. This saves you from typing the same options repeatedly.\n\n**Default path:** `~/.wpstaging/wpstaging.conf`\n\n**Example settings:**\n```ini\n--path /var/www/site\n--outputdir /var/www/backups\n```\n\n---\n\n## System Requirements\n\n**Minimum Requirements:**\n- **Extract/Restore:** Any modern system with 512 MB RAM and sufficient disk space\n- **Dockerize:** 2 CPU cores, 4 GB RAM, Docker 20.10.0+, Docker Compose 2.19.0+\n\n**License:** WP Staging Pro (Agency or Developer plan required)\n\nFor detailed system requirements, see [System Requirements Documentation](./docs/SYSTEM-REQUIREMENTS.md).\n\n---\n\n## Release Notes\n\nSee [CHANGELOG.md](./CHANGELOG.md) for detailed release history and version changes.\n\n---\n\n## FAQ and Troubleshooting\n\nFor common issues and troubleshooting guidance, refer to [FAQ.md](./docs/FAQ.md).\n\n---\n\n## Contributing\n\nWe'd love to hear from you!\nHave a problem or idea? Let us know through our issue tracker.\n\n- Submit an issue: https://github.com/wp-staging/wp-staging-cli-release/issues\n- Check for existing issues before submitting new ones.\n- Prebuilt binaries only — source contributions are not yet open.\n\n---\n\n## Acknowledgements\n\n- [WP Staging Pro](https://wp-staging.com/) — The best backup and migration plugin for WordPress.\n- [Go Programming Language](https://go.dev/) — The core language behind this tool.\n- [Cobra](https://github.com/spf13/cobra) — CLI framework for Go applications.\n- [bashunit](https://github.com/TypedDevs/bashunit) — Used for end-to-end testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwp-staging%2Fwp-staging-cli-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwp-staging%2Fwp-staging-cli-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwp-staging%2Fwp-staging-cli-release/lists"}