V5 Migration via WP-CLI

What is WP-CLI?

WP-CLI is a command-line tool that lets you manage a WordPress site using text-based commands in a terminal or SSH window without logging into the WordPress dashboard. It’s often used by developers or advanced users for tasks like plugin updates, content operations, and database management.

If you don’t know what WP-CLI is or how to access it, this guide may not be for you directly. Please ask your developer or hosting provider for assistance to ensure a safe and successful migration.

Why Use WP-CLI Migration?

The standard migration wizard in version 5 of WP RSS Aggregator can struggle with large data sets. If your site has more than 10,000 imported feed items, you may experience slowdowns, browser timeouts, or incomplete migrations.

WP-CLI avoids these issues by running the migration from your server’s command line. This allows for faster performance, better control, and fewer chances of failure.

We’ve successfully tested this method with over 100,000 feed items to ensure it can handle high-volume scenarios safely and efficiently.

When to Use WP-CLI Migration

Choose the WP-CLI migration method if:

• You have over 10,000 imported feed items.
• Items are missing after attempting the migration using the wizard.
• The standard migration didn’t complete successfully.
• You want to manually control and monitor the process.

Important: This method is recommended only for advanced users (developers or those with SSH/terminal access). If you’re not comfortable using command-line tools, please seek assistance from your developer or hosting provider.

Prerequisites

Access to WP-CLI

To use WP-CLI, you need to run commands from your server’s command line. This is typically done via SSH (Secure Shell), which allows you to securely access your site’s server from a terminal.

How to Access SSH:

1. Open your terminal (on macOS/Linux) or an SSH client like PuTTY (on Windows).
2. Connect to your site using a command like ssh username@yourdomain.com, replacing username and yourdomain.com with the connection details provided by your hosting provider.
3. Once connected, you’ll be inside your server’s environment where you can run WP-CLI commands.

Most managed WordPress hosts have WP-CLI pre-installed. If you’re unsure, check your host’s documentation or ask their support. Here are a few links to the most popular hosts’ documentation on WP-CLI:

• Servebolt
• Cloudways
• Pressable
• Kinsta
• Hostinger
• WP Engine
• GoDaddy
• Hosting.com
• InMotion Hosting
• SiteGround
• Rocket.net

Before You Start

In order to run the WP-CLI migration, you must be using Aggregator v5.0.0 or later on your website.

To do this:

1. Make sure all currently used v4 add‑on plugins on your site are active in the Plugins page.
2. Update the free core plugin to the latest version 5 release from your Plugins page.
3. Install and activate the WP RSS Aggregator – Premium plugin.
4. Go to RSS Aggregator > Settings > Switch to v5 to begin the migration process.

On the “Switch to v5” page you will find further instructions and videos that will guide you through the v5 changes and migration wizard.

The Migration Wizard

Click on the “Switch to v5” button at the bottom of the page and the v5 migration wizard will appear.

Click on the Start migration button to get started.

If at any time you wish to stop and cancel the migration to go back to v4, click on the Cancel migration and stay on v4 button.

The next screen highlights the new features and improvements in Aggregator v5. Click on the Next button to continue.

The next step is where you need to switch to v5 in order to run the WP-CLI migration. To do this, please click on the “Use WP-CLI Migration Method (Advanced)” button, as seen below.

Note that there are two versions of the WP-CLI notice in the migration wizard. If you have more than 10k imported items on your site, you will see the below version with an orange button.

Once the button is clicked, you will be taken to v5 in a blank state, as seen below.

Before proceeding to the next step, please click on the “Activate your license” link in the top yellow notice and enter your plan license key to activate any premium features available in your plan.

Next, proceed with the WP-CLI migration steps explained below in order to migrate your v4 data to v5.

Migration Steps

Step 1. Perform a Dry Run (Recommended)

Run the below command to preview what the migration will do, without making any actual changes on the site:

wp rss v4_migration run_all --dry-run

If you’re encountering issues during migration or wish to keep a copy of the migration process for your own records, use the below command to simulate the migration process and print a report to a file called migration-dry-run.log, which will be saved on your server.

wp rss v4_migration run_all --dry-run --yes --debug > migration-dry-run.log

Open the migration-dry-run.log file in a text editor to review the details or send it to our support team if you need any assistance.

Step 2. Run the Actual Migration

Once you’ve reviewed the dry run and are ready to proceed, run the real migration.

Option A: Run with Confirmation Prompt

This is the safer choice as it will ask you to manually confirm the migration run before continuing:

wp rss v4_migration run_all

Option B: Auto-Confirm and Run Immediately

To skip the confirmation prompt and start the migration right away, use the below command. Only use this only if you’re confident that everything is ready.

wp rss v4_migration run_all --yes

Below is an example of the migration command in action in the Terminal:

Command Reference

Command	Reference
--dry-run	Simulates the migration without changing any data.
--yes	Skips the confirmation prompt and runs immediately.
--dry-run --yes	Simulates and auto-confirms. Useful for scripting or automation.
--debug	Adds detailed output for troubleshooting. Can be combined with any of the above.

After the Migration

• The WP-CLI method does not delete your original v4 data.
• If a previous migration failed or was incomplete, you can safely retry using WP-CLI.
• For recovery options, go to: Aggregator > Settings > Advanced > Migration Recovery Options

Resetting the v5 Migration (Optional)

The CLI migration does not remove or overwrite any data by default. If you need to start the migration process from scratch, you can use the following WP-CLI command:

wp rss reset-v5

This command resets all v5-related data and settings, returning the plugin to a clean v5 state. It is intended for advanced use cases such as:

• Cleaning up after a failed or incomplete migration
• Repeating a fresh migration test
• Resetting a staging environment

Warning: This will delete all v5 data (feeds, settings, imported items, etc.). Your original v4 data will remain untouched and any v4 premium add-ons on the site will remain activated, but v5 will return to its default installation state. Use this only if you are sure you want to fully reset the v5 plugin.

Below is an example of the reset command in action in the Terminal:

Final Reminder

Before proceeding:

• Back up your site completely.
• Get help from your developer or host if you’re unsure about using SSH or WP-CLI.

This process is designed for users who are comfortable with the command line. If you’re not, it’s better to ask for support than to risk data issues.