WP-CLI

WP-CLI is a command-line interface for WordPress that you can access when connected via SSH. This guide covers the most commonly used commands and their associated sub-commands.

This feature is available on sites with the WordPress.com Creator or Entrepreneur plan.

Access CLI

WP-CLI comes preinstalled on WordPress.com and extends the shell to provide WordPress-specific command line tools. You can start running WP-CLI commands once you have connected to SSH. Visit the SSH guide to learn how to activate and use SSH.

Common Commands

There are a number of commands that you may find helpful when working with your site. These commands and their common parameters are included below. There are also many other useful commands available, and these sections do not include them all. Please refer to the WordPress.org Developer CLI Commands Guide for more information.

In the CLI itself you can also make use of the help command to find more information about what parameters and flags are available. For example: wp help plugin.

Manage Users

Use the following commands to manage your site’s local users. Please keep in mind that changing user aspects in CLI will not change the settings for WordPress.com user accounts that may be associated with local accounts.

The user serving as your primary Jetpack connection must have an email that matches the email of the site owner’s WordPress.com account. If the email does not match, the site’s Jetpack Connection will not work correctly. The username does not need to match.

Command	Description
`wp user list`	List all users on the site If you have many users you may wish to restrict the list to specific roles by adding `--role={ROLE}`
`wp user get {USER ID/NAME/EMAIL}`	Return a specific user
`wp user create {NAME} {USER EMAIL} --role={ROLE}`	Create a new user with the name, user email, and role defined This command will automatically create and return a secure password for the user This command does not create a matching WordPress.com user. If you are using WordPress.com Secure Sign-On (SSO) you should instead create the local user by inviting a user via Users > Add New. This will ensure a WordPress.com account and local user are both created.
`wp user update {USER ID/NAME/EMAIL`} `--{KEY}={VALUE}`	Update a user Keys include `display_name`, `user_email`, `role`, and `user_pass`
`wp user reset-password` {`USER ID/NAME/EMAIL`}	Reset a user password with a random secure string This command can take multiple users if you put a space between each ID If you do not wish to notify users of password resets you can add `--skip-email`
`wp user add-role {USER ID} {ROLE}`	Add a role to a user This can be used to add default and custom roles
`wp user remove-role {USER ID} {ROLE}`	Remove a role from a user
`wp user delete {USER ID/NAME/EMAIL} --reassign={USER ID/NAME/EMAIL}`	Delete a user If you do not include the `--reassign={USER ID/NAME/EMAIL}` flag all content created by the user will be deleted

Note: You will not be able to update a user’s user_login with the wp user update command. Instead, updating the user_login requires using wp search-replace. This change, however, is not recommended as it performs partial replacements. For example: If there are two users with the usernames “techie” and “nontechie”, replacing “techie” with “sense” will result in “sense” and “nonsense”.

If you would still like to replace a user_login the command to use is:

wp --skip-plugins --skip-themes search-replace "old username" "new username" *users --include-columns=user_login,user_nicename --dry-run

Manage Plugins and Themes

Use the following commands to manage your plugins and themes. When working with plugins and themes, please note that the related slug will not always match the plugin/theme name.

If you are having issues with a plugin or theme you can start your command with wp --skip-themes --skip-plugins to run the commands despite conflicts.

You can find more information about skip commands below.

Command	Description
`wp plugin list` `wp theme list`	List all the plugins/themes installed on the site and their status. From these lists you will find the slugs of your installed plugins and themes, which you can use for the purpose of running the commands below.
`wp plugin activate {SLUG}` `wp theme activate {SLUG}`	Activate the specified plugin/theme To deactivate a theme you need to activate another in its place
`wp plugin deactivate {SLUG}`	Deactivate the specified plugin
`wp plugin delete {SLUG}` `wp theme delete {SLUG}`	Delete the specified plugin/theme You cannot delete an active theme or managed themes with this command. To remove an active theme, switch to a different theme first, then delete the theme that you want. To remove managed themes, you may do so via SFTP.
`wp plugin install {PLUGIN SLUG or URL TO INSTALLATION_FILE}` `wp theme install {PLUGIN SLUG or URL TO INSTALLATION_FILE}`	Install a plugin from the WordPress.org repo based on the plugin’s slug or via a URL path to an installation .zip file You can not overwrite an existing plugin/theme unless you run the command with the `--force` flag. You can use this to update plugins and fix corrupt plugin folders. To automatically activate the plugin after installation, include the `--activate` flag
`wp plugin update {SLUG}` `wp theme update {SLUG}`	Update the specified plugin if available. You cannot use this command to update managed plugins/themes. You can also use the `--all` flag if you want to update all plugins
`wp plugin auto-updates {COMMAND} {PLUGIN SLUG}`	Display the status of plugin updates or enable/disable updates for a specific plugin COMMANDS are `status`, `enable`, `disable` You cannot disable updates for managed plugins or themes

Manage Jetpack

Use the following commands to adjust Jetpack modules, check your Jetpack connection, or troubleshoot Jetpack issues.

Disconnecting Jetpack will disable many important WordPress.com features including general site and billing management.

Using --skip-plugins will prevent these commands from working.

You can find more information about skip commands below.

Command	Description
`wp jetpack module list`	List the Jetpack modules and their statuses
`wp jetpack module activate` `{MODULE NAME}`	Activate the specified Jetpack module You can also use `all` in place of `{MODULE NAME}`
`wp jetpack module deactivate {MODULE NAME}`	Deactivate the specified Jetpack module You can also use `all` in place of `{MODULE NAME}`
`wp jetpack status`	Report the status of Jetpack, including which user account is the primary connection (this should always be the site owner) An additional parameter, `full`, can be added to report full details, including Jetpack version, WordPress version, and module status
`wp jetpack sync start`	Force a new Jetpack sync, between WordPress.com and the WordPress installation Note: Jetpack automatically syncs at certain intervals so this command is typically not necessary. If you do run this command, be advised that it is resource intensive and can slow your site until the sync is complete
`wp jetpack disconnect` `blog`	Disconnect the currently connected site If you disconnect Jetpack you will need to reconnect it in order for your site to function correctly. A disconnected Jetpack will prevent your site from properly backing up data and will interfere with Jetpack functions such as scheduled posts, subscriptions, VideoPress, etc.
`wp jetpack disconnect user {USER ID/NAME/EMAIL}`	Disconnect a specific user from the currently connected site

While your site’s visibility is set to Private, some Jetpack modules are disabled and cannot be managed in CLI. These modules are: Ads, Asset CDN, Enhanced Distribution, Google Analytics, Image CDN, JSON API, Publicize, Sharing, Site Verification, and Sitemaps.

Manage Site Settings

Use the following commands to manage various aspects of your site and users.

Command	Description
`wp site empty --yes`	Empty a site of content (posts and pages)
`wp site empty --uploads --yes`	Empty the site, including media files

wp site empty commands are irreversible. If you use them, your content will be removed permanently. To recover them, you will need to restore from a previous backup. Please ensure you have a backup available before using the function.

wp site commands will not delete themes or plugins, nor will they reset a theme or erase plugin settings. If you need to reset your site completely, please reach out to WordPress.com support.

Command	Description
`wp option get {OPTION}`	Return the value of an option
`wp option update {OPTION} {VALUE}`	Update the value of an option
`wp option add {OPTION} {VALUE}`	Add a new option
`wp option delete {OPTION}`	Delete an option

The options table is the “control center” of a website. If an option is improperly edited or deleted, you may stop your entire site from working.

When working with wp option commands, if you get the following error in CLI it may mean the options table has been corrupted:

One or more database tables are unavailable. The database may need to be repaired.

You can restore the table by rewinding the site’s SQL table to a last good copy. Please note, this will reverse all mutable changes to the database that occur after the restore point and can result in lost data.

To restore an SQL table:

In the site’s dashboard, navigate to Jetpack > Activity Log.
Select a backup point to rewind to.
Uncheck all boxes except for Site Database (SQL).
Click Confirm Rewind.

Command	Description
`wp role list`	Return a list of roles
`wp role reset {ROLE}`	Reset the specified role You can list multiple roles (without comma) You can also replace {ROLE} with `--all` to reset all at once

Manage Content

You can use the following commands to manage your site content, including posts/pages, menus, and media.

Command	Description
`wp post list`	Return a list of blog posts You can use a variety of flags with this command, including: `--format={FORMAT}` `--posts_per_page={#}` `--post_type={TYPE}` Post types include `posts`, `pages`, `attachments`, and `products` Multiple flags can be used at once ex: `wp post list --post_type=posts,pages --format=count`
`wp post update {POST_ID} --{KEY}={VALUE}`	Update post information ex: `wp post update123 --post_status=draft`
`wp post delete {POST_ID}`	Delete a post
`wp post exists {POST_ID}`	Check if a post exists

Command	Description
`wp menu list`	List menus on the site
`wp menu item list {TERM_ID}`	List menu items of a specific menu
`wp menu item update {MENU_ITEM_PARENT_ID}`	Update a specific menu item

The wp menu commands can be useful if you see the primary menu freezing in the Customizer or /wp-admin screen.

Command	Description
`wp media regenerate`	Regenerate media thumbnails when the Jetpack Photon module is deactivated You can add `--only-missing` to the end to skip existing image sizes

Troubleshooting Site Issues

You can use the following commands when troubleshooting issues on your site. Checking for PHP errors can help you identify sources of errors on your site or use wp wpcomsh commands to quickly perform plugin conflict checks or to adjust whether or not you are using managed versions of plugins.

Both Jetpack and Akismet are managed plugins that are required for your site to work correctly here at WordPress.com. These plugins should remain activated and cannot be switched to unmanaged versions.

Command	Description
`wp php-errors`	Output error logs in WP-CLI This command only outputs PHP errors, not of any other language such as HTML, Javascript, or CSS. To see these other errors, use the Browser Inspector You can add `--limit={#}` to reduce the number of errors shown to improve readability
`wp wpcomsh deactivate-user-plugins`	Deactivate user plugins You can add the `--interactive` flag to the end of the command to force confirmation for each plugin This command will not deactivate Akismet, Jetpack, or managed ecommerce plugins
`wp wpcomsh reactivate-user-plugins`	Reactivate user plugins You can add the `--interactive` flag to the end of the command to force confirmation for each plugin
`wp wpcomsh persistent-data {DATA}`	Return persistent data (which Jetpack uses to verify site capabilities) Available `{DATA}` include: `WPCOM_PLAN_EXPIRATION` `JETPACK_BLOG_TOKEN` `WPCOM_PURCHASES` `WPCOM_PUBLIC_COMING_SOON`
`wp wpcomsh plugin use-managed {SLUG}`	Use a managed (symlinked) version of a plugin This command will remove existing, unmanaged versions and replace them with managed versions. It is available for `amp`, `classic-editor`, `coblocks`, `crowdsignal-forms`, `full-site-editing`, `gutenberg`, `layout-grid`, `page-optimize`, `wp-seo`, `woocommerce`, WooCommerce Extensions from the WordPress.com Marketplace and plugins included in the Entrepreneur plan. You can add `--remove-existing` to skip the confirmation step
wp wpcomsh theme use-managed {SLUG}	Use a managed (symlinked) version of a theme This command will remove existing, unmanaged versions and replace them with managed versions. It is available for all WordPress.com themes, Storefront, and any Twenty * themes (ex: Twenty Twenty Two) You can add `--remove-existing` to skip the confirmation step
`wp wpcomsh plugin use-unmanaged {SLUG}`	Use an unmanaged (not symlinked) version of a plugin This command will remove existing, managed versions and replace them with unmanaged versions from the WordPress.org plugin repository. It will not work for WooCommerce Extensions from the WordPress.com Marketplace and plugins included in the Entrepreneur plan. You will need to install these plugins manually to get the unmanaged version. You can add `--remove-existing` to skip the confirmation step and `--version={X.Y.Z`} to define the version to install
wp wpcomsh theme use-unmanaged {SLUG}	Use an unmanaged (not symlinked) version of a theme This command will remove existing, managed versions and replace them with unmanaged versions from the WordPress.org theme repository if available. You can add `--remove-existing` to skip the confirmation step and `--version={X.Y.Z`} to define the version to install

The WordPress.com Site Helper or wpcomsh must-use plugin runs on sites with activated hosting features to make them work seamlessly in the WordPress.com ecosystem.

Command	Description
`wp cache flush`	Flush the cache This command is not meant to be a fix for issues and can obscure root causes. Please use with care. Clearing the cache may also make your site run slower while the cache is rebuilt on page load.

Skipping Plugins and Themes

You may want to skip plugins, and sometimes themes, when running CLI commands. This can be useful for troubleshooting conflicts or for overriding restrictions placed by plugins, such as control over roles.

--skip-plugins can be added before any command and skips plugins
--skip-themes can be added before any command and skips themes

You can use these commands together. You can also use these commands with slugs to skip specific plugins or themes. This can be useful for ruling out the effects of certain plugins or themes when deactivation is not possible.

For example: wp --skip-plugins=woocommerce, code-snippets, elementor-pro plugin list

CLI Restrictions

In order to provide a secure and performant environment, we restrict certain CLI commands. If a command is restricted, it will return forbidden in the CLI.

Typically, you can do pretty much anything on CLI that you could do with the GUI (Graphical User Interface) in your site’s dashboard, but without any of the warnings or checks provided in the GUI. For example, the wp site empty --yes command will empty your site’s content without confirmation. With these restrictions, it’s harder to accidentally destroy a site.

Troubleshooting CLI

Occasionally, you may see HTML returned when you enter a command in the CLI. This can happen when you have a maintenance plugin active or can be a sign that a theme or plugin is coded incorrectly.

If no maintenance plugin is present, you can use the --skip-* commands to verify whether the source is a plugin or theme. Once identified, you can deactivate the plugin or theme and may want to reach out to the plugin developer to get it corrected.

Due to the complex nature of WP-CLI commands, we are not able to provide extensive support for using these tools. Happiness Engineers are available to help with issues accessing WP-CLI but cannot guide you through using commands.

Additional WP-CLI Resources

Last updated: April 11, 2024