← ServerPilot Docs

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 app's system user—not as the root user.

Then, navigate to your app's public directory by entering the following commands, replacing "APPNAME" with your app's name:

cd apps
cd APPNAME
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   |     @serverpilot.io | 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 newuser@mydomain.com --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.