How to use WP-CLI
The full list of WP-CLI commands is available in the official WP-CLI documentation.
This series will walk you through using WP-CLI to quickly and easily perform administrative tasks on your WordPress site.
- How to Manage WordPress Users with WP-CLI
Manage your users from the command line over SSH. - How to Manage WordPress Themes with WP-CLI
Quickly add and remove WordPress themes. - How to Manage WordPress Plugins with WP-CLI
Efficiently install, activate, and deactivate plugins individually or all at once. - How to Use the Search and Replace Function of WP-CLI
A detailed description of one of most useful, yet most advanced, features of WP-CLI.
This is a detailed description of one of most useful, yet most advanced, features of WP-CLI.
WP-CLI allows you to use the command line to manage your WordPress installations. Everything from updating plugins to deleting comments (and much more) can be done without using a web browser.
NOTE
JungleWP installs WP-CLI on your Pod by default.
To use WP-CLI, SSH into your server and run the command:
wp
WP-CLI is a powerful tool that allows you to use the command line over SSH to manage your WordPress installations. Everything from updating plugins to deleting comments (and much more) can be done without using a web browser. This is especially useful if you are unable to access the wp-admin area of your WordPress site.
You can call WP-CLI by using this command as your WordPress website's Pod user:
wp
You can can also configure the PHP version used when you call just the wp command.
The full list of WP-CLI commands is available in the official WP-CLI documentation.
This series will walk you through using WP-CLI to quickly and easily perform administrative tasks on your WordPress site.
1- How to Manage WordPress Users with WP-CLI
Managing WordPress users over SSH is quick and easy with WP-CLI.
To use WP-CLI, SSH in to your server as your WordPress Website's Pod user—not as the root user.
Then, navigate to your website's public directory by entering the following commands, replacing "WEBSITENAME" with your app's name:
cd apps cd WEBSITENAME cd public
WP-CLI allows you to accomplish several tasks related to WordPress users. For instance, if you type wp user and press Enter, WP-CLI will offer the arguments accepted for this command:
usage: wp user add-cap <user> <cap> or: wp user add-role <user> <role> or: wp user create <user-login> <user-email> [--role=<role>] [--user_pass=<password>] [--user_registered=<yyyy-mm-dd>] [--display_name=<name>] [--first_name=<first_name>] [--last_name=<last_name>] [--send-email] [--porcelain] or: wp user delete <user>... [--network] [--reassign=<user-id>] [--yes] or: wp user generate [--count=<number>] [--role=<role>] [--format=<format>] or: wp user get <user> [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp user import-csv <file> [--send-email] [--skip-update] or: wp user list [--role=<role>] [--<field>=<value>] [--network] [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp user list-caps <user> [--format=<format>] or: wp user meta <command> or: wp user remove-cap <user> <cap> or: wp user remove-role <user> [<role>] or: wp user session <command> or: wp user set-role <user> [<role>] or: wp user term <command> or: wp user update <user>... --<field>=<value> See 'wp help user <command>' for more information on a specific command.
What follows are the most common times you would use WP-CLI to manage your users.
To List Existing Users
Enter this command to see a list of all your WordPress users:
wp user list
The output will look similar to the following:
+----+------------+--------------+---------------------+---------------------+---------------+ | ID | user_login | display_name | user_email | user_registered | roles | +----+------------+--------------+---------------------+---------------------+---------------+ | 1 | test-admin | test-admin | @example .com | 2017-03-28 23:26:59 | administrator | +----+------------+--------------+---------------------+---------------------+---------------+
This summarizes the following information about your users: their usernames to log in to your site's WordPress Dashboard, the names displayed on their posts, the dates they registered as users, and their roles.
To Create a New User
Enter this command to create a new administrator user, replacing "NEWUSERNAME" and "EMAILADDRESS" with your user's information:
wp user create NEWUSERNAME EMAILADDRESS --role=administrator
When executed without a password argument, the system will generate a random secure password similar to the following:
wp user create newuser [email protected] --role=administrator Success: Created user 3. Password: 0S4Ec(VuioxU
You can set the password with the --user_pass command, replacing "MySecurePasswordGoesHere" with your password:
wp user create NEWUSERNAME EMAILADDRESS --role=administrator --user_pass=MySecurePasswordGoesHere
To Change a User's Password
Enter this command to change a user's password:
wp user update USERNAME --user_pass=MyNewSecurePassword
To Remove a User
If you with to remove a user that does not have any posts you want to preserve, you can do so with this command, replacing "USERNAME" with the user:
wp user delete USERNAME
You'll receive a prompt that the system will delete any posts for this user; press y if you wish to proceed.
If the user has posts you would like to save, you can select another user to assign them to by entering this command and substituting the appropriate usernames for the fields shown in ALL CAPS:
wp user delete USERNAME --reassign=ANOTHERUSER
To Change a User's Role
WordPress users can be assigned different roles, and each role has different privileges. The available roles are
- administrator,
- editor,
- author,
- contributor, and
- subscriber.
To assign a role, enter the following command, replacing "USERNAME" and "ROLE" with the appropriate terms:
wp user update USERNAME --role=ROLE
For example,
wp user update newuser --role=editor
Check the official WP-CLI documentation for additional information.
2- How to Manage WordPress Themes with WP-CLI
Type wp theme and press Enter. You'll be given a list of the acceptable arguments for this command:
usage: wp theme activate <theme> or: wp theme delete <theme>... or: wp theme disable <theme> [--network] or: wp theme enable <theme> [--network] [--activate] or: wp theme get <theme> [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp theme install <theme|zip|url>... [--version=<version>] [--force] [--activate] or: wp theme is-installed <theme> or: wp theme list [--<field>=<value>] [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp theme mod <command> or: wp theme path [<theme>] [--dir] or: wp theme search <search> [--per-page=<per-page>] [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp theme status [<theme>] or: wp theme update [<theme>...] [--all] [--format=<format>] [--version=<version>] [--dry-run] See 'wp help theme <command>' for more information on a specific command.
This tutorial will cover the most common uses for wp theme.
To List Installed Themes
Enter this command to show a summary of your installed themes' various states:
wp theme list
The output will look similar to the following:
+-----------------+----------+--------+---------+ | name | status | update | version | +-----------------+----------+--------+---------+ | twentyfifteen | inactive | none | 1.7 | | twentyseventeen | active | none | 1.1 | | twentysixteen | inactive | none | 1.3 | +-----------------+----------+--------+---------+
This displays the active theme, any available updates for your themes, and the present version of the theme installed on your app.
To Install a New Theme
Enter this command to install a new theme, replacing "THEMENAME" with the name of the theme you would like to install:
wp theme install THEMENAME
This will give an output similar to the following as your theme is installed:
wp theme install twentyfifteen Installing Twenty Fifteen (1.7) Downloading install package from https://downloads.wordpress.org/theme/twentyfifteen.1.7.zip... Unpacking the package... Installing the theme... Theme installed successfully. Success: Installed 1 of 1 themes.
If the system is unable to locate a theme with the provided name, it will fail like so:
wp theme wrongtheme Error: 'wrongtheme' is not a registered subcommand of 'theme'. See 'wp help theme'.
To Install and Activate a Theme with a Single Command
You can also activate a theme when you install it by using this command:
wp theme install THEMENAME --activate
To Update One Theme
Enter this command to easily update one theme:
wp theme update THEMENAME
The system will display a success or failure message.
To Update All Themes
You can update all of your themes by entering this command:
wp theme update --all
The system will display a success or failure message.
To Activate a Theme
Enter this command to activate a theme:
wp theme activate THEMENAME
You will receive a message similar to this when the task is complete:
wp theme activate twentysixteen Success: Switched to 'Twenty Sixteen' theme.
To Delete a Theme
First, make sure the theme is not active by listing all themes:
wp theme list
Then, delete the chosen theme by typing the following, using the exact name of the theme in the list:
wp theme delete THEMENAME
Your results will look similar to the following:
wp theme delete twentyfifteen Deleted 'twentyfifteen' theme. Success: Deleted 1 of 1 themes.
You can find more information in the official WP-CLI documentation.
3- How to Manage WordPress Plugins with WP-CLI
Type wp plugin and press Enter. You'll be given a list of the acceptable arguments for this command:
usage: wp plugin activate [<plugin>...] [--all] [--network] or: wp plugin deactivate [<plugin>...] [--uninstall] [--all] [--network] or: wp plugin delete <plugin>... or: wp plugin get <plugin> [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp plugin install <plugin|zip|url>... [--version=<version>] [--force] [--activate] [--activate-network] or: wp plugin is-installed <plugin> or: wp plugin list [--<field>=<value>] [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp plugin path [<plugin>] [--dir] or: wp plugin search <search> [--page=<page>] [--per-page=<per-page>] [--field=<field>] [--fields=<fields>] [--format=<format>] or: wp plugin status [<plugin>] or: wp plugin toggle <plugin>... [--network] or: wp plugin uninstall <plugin>... [--deactivate] [--skip-delete] or: wp plugin update [<plugin>...] [--all] [--format=<format>] [--version=<version>] [--dry-run] See 'wp help plugin <command>' for more information on a specific command.
This article will cover the most common uses for wp plugin.
To List All Installed Plugins
Enter this command to see an overview of the state of your installed plugins:
wp plugin list
The output will look similar to the following:
+---------+----------+--------+---------+ | name | status | update | version | +---------+----------+--------+---------+ | akismet | inactive | none | 3.3 | | hello | inactive | none | 1.6 | +---------+----------+--------+---------+
This displays the official name of each of your plugins, the current status, available updates, and the installed version.
To Install a New Plugin
Enter this command to install a new theme, replacing "PLUGINNAME" with the name of the plugin you would like to install:
wp plugin install PLUGINNAME
This will give you an output similar to the following as your plugin is installed:
Installing Jetpack by WordPress.com (4.8.2) Downloading install package from https://downloads.wordpress.org/plugin/jetpack.4.8.2.zip... Unpacking the package... Installing the plugin... Plugin installed successfully. Success: Installed 1 of 1 plugins.
You can activate the plugin at installation by amending the command like this:
wp plugin install PLUGINNAME --activate
To Activate a Plugin
Enter this command to activate a plugin:
wp plugin activate PLUGINNAME
You will receive a message similar to this upon success:
Plugin 'hello' activated. Success: Activated 1 of 1 plugins.
To Update One Plugin
Enter this command to easily update one plugin:
wp plugin update PLUGINNAME
The system will show a success or failure message.
To Update All Plugins
You can update all of your plugins by entering this command:
wp plugin update --all
The system will show a success or failure message for each installed plugin.
To Deactivate One Plugin
Enter this command to deactivate one plugin:
wp plugin deactivate PLUGINNAME
To Deactivate All Plugins
You can deactivate all of your plugins by entering this command:
wp plugin deactivate --all
Deactivating your plugins will not delete the plugins; it will only make them inactive. The system will show each plugin as deactivated. The system will also note any failures and provide a summary of the successfully deactivated plugins, similar to this:
Plugin 'akismet' deactivated. Plugin 'hello' deactivated. Plugin 'jetpack' deactivated. Success: Deactivated 3 of 3 plugins.
To Delete One Plugin
Enter this command to delete a plugin:
wp plugin delete PLUGINNAME
You will receive a result similar to the following:
Deleted 'jetpack' plugin. Success: Deleted 1 of 1 plugins.
It is not necessary to deactivate a plugin before deleting it.
You can find more information in the official WP-CLI documentation.
4- How to Use the Search and Replace Function of WP-CLI
One of the more advanced features of WP-CLI is its powerful search and replace function. Search-replace is very handy when changing a site's URL or other frequently appearing text inside a WordPress database. It can save a vast amount of time over manually updating these values and is much easier than crafting a raw MySQL query to do the same thing.
Type wp search-replace and press Enter. WP-CLI will offer the acceptable arguments for this command:
usage: wp search-replace <old> <new> [<table>...] [--dry-run] [--network] [--all-tables-with-prefix] [--all-tables] [--export[=<file>]] [--export_insert_size=<rows>] [--skip-columns=<columns>] [--include-columns=<columns>] [--precise] [--recurse-objects] [--verbose] [--regex] [--regex-flags=<regex-flags>]
You can also use wp help search-replace for additional help.
Even though many options are possible with wp search-replace, this tutorial will cover the most common use: changing all instances of one domain to another.
A very useful feature of wp search-replace is its ability to not only scan the entire database but also unpack JSON payloads within the database, performing its tasks on them as well.
The wp search-replace function is somewhat peculiar in its case sensitivity; for the best results, match cases exactly and search for other capitalization instances using the --dry-run option.
One of the most notable and helpful flags for wp search-replace is the --dry-run switch. This will show you what would be changed by the command you have entered, giving you the opportunity to correct potential mistakes without making changes or causing damage to your WordPress website.
If the --dry-run flag is not used, all instances of the first value will be replaced by the second.
Replacing a Domain Name
First, do a dry run for safety:
wp search-replace olddomain.com newdomain.com --dry-run
The output will display the database table names, columns, how many replacements would be made within each table, and what type of data each table contains; however, no changes will actually be made.
+------------------------+-----------------+--------------+------+ | Table | Column | Replacements | Type | +------------------------+-----------------+--------------+------+ | wp_c7734cd387_comments | comment_content | 0 | SQL | | wp_c7734cd387_links | link_url | 0 | SQL | | wp_c7734cd387_links | link_image | 0 | SQL | | wp_c7734cd387_options | option_value | 2 | SQL | | wp_c7734cd387_posts | post_content | 1 | SQL | | wp_c7734cd387_posts | post_title | 0 | SQL | | wp_c7734cd387_posts | guid | 2 | SQL | | wp_c7734cd387_users | display_name | 0 | SQL | +------------------------+-----------------+--------------+------+ Success: 5 replacements to be made.
In the sample above, the output shows "5 replacements to be made"; if the --dry-run flag was not used, the output would show "made X replacements."
After verifying the changes look correct in your dry run, it's time to actually make the changes by running the wp search-replace without the --dry-run flag:
wp search-replace olddomain.com newdomain.com
This time, the output is almost identical with the exception of the Success message as shown in the example below:
+------------------------+-----------------+--------------+------+ | Table | Column | Replacements | Type | +------------------------+-----------------+--------------+------+ | wp_c7734cd387_comments | comment_content | 0 | SQL | | wp_c7734cd387_links | link_url | 0 | SQL | | wp_c7734cd387_links | link_image | 0 | SQL | | wp_c7734cd387_options | option_value | 2 | SQL | | wp_c7734cd387_posts | post_content | 1 | SQL | | wp_c7734cd387_posts | post_title | 0 | SQL | | wp_c7734cd387_posts | guid | 2 | SQL | | wp_c7734cd387_users | display_name | 0 | SQL | +------------------------+-----------------+--------------+------+ Success: Made 5 replacements.
Other Uses for the Search and Replace Function
As mentioned earlier, many options exist for wp search-replace. You can use the function on any string within the database, including email addresses and image names.
Use the following command, followed by any flags and arguments you wish to provide:
wp search-replace EXISTING-STRING NEW-STRING
More information can be found in the official WP-CLI documentation.