WordPress at a glance
Home Handbook WP-CLI Commands

wp user

Manages users, along with their roles, capabilities, and meta.

Commands Description
Lists users.
Gets details about a user.
Deletes one or more users from the current site.
Creates a new user.
Updates an existing user.
Generates some users.
Sets the user role.
Adds a role for a user.
Removes a user's role.
Adds a capability to a user.
Removes a user's capability.
Lists all capabilities for a user.
Imports users from a CSV file.
Resets the password for one or more users.
Marks one or more users as spam.
Removes one or more users from spam.
Checks if a user's password is valid or not.
List all metadata associated with an object.
Get meta field value.
Delete a meta field.
Add a meta field.
Update a meta field.
Get a nested value from a meta field.
Update a nested value for a meta field.
List all terms associated with an object.
Remove a term from an object.
Add a term to an object.
Set object terms.
Destroy a session for the given user.
List sessions for the given user.

Examples

# List user IDs
$ wp user list --field=ID
1

# Create a new user.
$ wp user create bob bob@example.com --role=author
Success: Created user 3.
Password: k9**&I4vNH(&

# Update an existing user.
$ wp user update 123 --display_name=Mary --user_pass=marypass
Success: Updated user 123.

# Delete user 123 and reassign posts to user 567
$ wp user delete 123 --reassign=567
Success: Removed user 123 from http://example.com

Source code of the commands


menu

wp user list

Lists users.

Display WordPress users based on all arguments supported by WP_User_Query().

Usage

wp user list [--role={role}] [--{field}={value}] [--network] [--field={field}] [--fields={fields}] [--format={format}]

You can specify global options and the following:

[--role={role}]
Only display users with a certain role.
[--{field}={value}]
Control output by one or more arguments of WP_User_Query().
[--network]
List all users in the network for multisite.
[--field={field}]
Prints the value of a single field for each user.
[--fields={fields}]
Limit the output to specific object fields.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • ids
  • json
  • count
  • yaml

Available fields

These fields will be displayed by default for each user:

  • ID
  • user_login
  • display_name
  • user_email
  • user_registered
  • roles

These fields are optionally available:

  • user_pass
  • user_nicename
  • user_url
  • user_activation_key
  • user_status
  • spam
  • deleted
  • caps
  • cap_key
  • allcaps
  • filter
  • url

Examples

# List user IDs
$ wp user list --field=ID
1
# List users with administrator role
$ wp user list --role=administrator --format=csv
ID,user_login,display_name,user_email,user_registered,roles
1,supervisor,supervisor,supervisor@gmail.com,"2016-06-03 04:37:00",administrator
# List users with only given fields
$ wp user list --fields=display_name,user_email --format=json
[{"display_name":"supervisor","user_email":"supervisor@gmail.com"}]
# List users ordered by the 'last_activity' meta value.
$ wp user list --meta_key=last_activity --orderby=meta_value_num
menu

wp user get

Gets details about a user.

Usage

wp user get {user} [--field={field}] [--fields={fields}] [--format={format}]

You can specify global options and the following:

{user}
User ID, user email, or user login.
[--field={field}]
Instead of returning the whole user, returns the value of a single field.
[--fields={fields}]
Get a specific subset of the user's fields.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • json
  • yaml

Examples

# Get user
$ wp user get 12 --field=login
supervisor
# Get user and export to JSON file
$ wp user get bob --format=json > bob.json

wp user delete

Deletes one or more users from the current site.

On multisite, wp user delete only removes the user from the current site. Include --network to also remove the user from the database, but make sure to reassign their posts prior to deleting the user.

Usage

wp user delete {user}... [--network] [--reassign={user-id}] [--yes]

You can specify global options and the following:

{user}...
The user login, user email, or user ID of the user(s) to delete.
[--network]
On multisite, delete the user from the entire network.
[--reassign={user-id}]
User ID to reassign the posts to.
[--yes]
Answer yes to any confirmation prompts.

Examples

# Delete user 123 and reassign posts to user 567
$ wp user delete 123 --reassign=567
Success: Removed user 123 from http://example.com
# Delete all contributors and reassign their posts to user 2
$ wp user delete $(wp user list --role=contributor --field=ID) --reassign=2
Success: Removed user 813 from http://example.com
Success: Removed user 578 from http://example.com
menu

wp user create

Creates a new user.

Usage

wp user create {user-login} {user-email} [--role={role}] [--user_pass={password}] [--user_registered={yyyy-mm-dd-hh-ii-ss}] [--display_name={name}] [--user_nicename={nice_name}] [--user_url={url}] [--nickname={nickname}] [--first_name={first_name}] [--last_name={last_name}] [--description={description}] [--rich_editing={rich_editing}] [--send-email] [--porcelain]

You can specify global options and the following:

{user-login}
The login of the user to create.
{user-email}
The email address of the user to create.
[--role={role}]
The role of the user to create. Default: default role. Possible values include 'administrator', 'editor', 'author', 'contributor', 'subscriber'.
[--user_pass={password}]
The user password. Default: randomly generated.
[--user_registered={yyyy-mm-dd-hh-ii-ss}]
The date the user registered. Default: current date.
[--display_name={name}]
The display name.
[--user_nicename={nice_name}]
A string that contains a URL-friendly name for the user. The default is the user's username.
[--user_url={url}]
A string containing the user's URL for the user's web site.
[--nickname={nickname}]
The user's nickname, defaults to the user's username.
[--first_name={first_name}]
The user's first name.
[--last_name={last_name}]
The user's last name.
[--description={description}]
A string containing content about the user.
[--rich_editing={rich_editing}]
A string for whether to enable the rich editor or not. False if not empty.
[--send-email]
Send an email to the user with their new account details.
[--porcelain]
Output just the new user id.

Examples

# Create user
$ wp user create bob bob@example.com --role=author
Success: Created user 3.
Password: k9**&I4vNH(&
# Create user without showing password upon success
$ wp user create ann ann@example.com --porcelain
4
menu

wp user update

Updates an existing user.

Usage

wp user update {user}... [--user_pass={password}] [--user_nicename={nice_name}] [--user_url={url}] [--user_email={email}] [--display_name={display_name}] [--nickname={nickname}] [--first_name={first_name}] [--last_name={last_name}] [--description={description}] [--rich_editing={rich_editing}] [--user_registered={yyyy-mm-dd-hh-ii-ss}] [--role={role}] --{field}={value} [--skip-email]

You can specify global options and the following:

{user}...
The user login, user email or user ID of the user(s) to update.
[--user_pass={password}]
A string that contains the plain text password for the user.
[--user_nicename={nice_name}]
A string that contains a URL-friendly name for the user. The default is the user's username.
[--user_url={url}]
A string containing the user's URL for the user's web site.
[--user_email={email}]
A string containing the user's email address.
[--display_name={display_name}]
A string that will be shown on the site. Defaults to user's username.
[--nickname={nickname}]
The user's nickname, defaults to the user's username.
[--first_name={first_name}]
The user's first name.
[--last_name={last_name}]
The user's last name.
[--description={description}]
A string containing content about the user.
[--rich_editing={rich_editing}]
A string for whether to enable the rich editor or not. False if not empty.
[--user_registered={yyyy-mm-dd-hh-ii-ss}]
The date the user registered.
[--role={role}]
A string used to set the user's role.
--{field}={value}
One or more fields to update. For accepted fields, see wp_update_user().
[--skip-email]
Don't send an email notification to the user.

Examples

# Update user
$ wp user update 123 --display_name=Mary --user_pass=marypass
Success: Updated user 123.
menu

wp user generate

Generates some users.

Creates a specified number of new users with dummy data.

Usage

wp user generate [--count={number}] [--role={role}] [--format={format}]

You can specify global options and the following:

[--count={number}]
How many users to generate?
Default: 100
[--role={role}]
The role of the generated users. Default: default role from WP
[--format={format}]

Render output in a particular format.
Default: progress
Can be:

  • progress
  • ids

Examples

# Add meta to every generated users.
$ wp user generate --format=ids --count=3 | xargs -d ' ' -I % wp user meta add % foo bar
Success: Added custom field.
Success: Added custom field.
Success: Added custom field.

wp user set-role

Sets the user role.

Usage

wp user set-role {user} [{role}]

You can specify global options and the following:

{user}
User ID, user email, or user login.
[{role}]
Make the user have the specified role. If not passed, the default role is used.

Examples

$ wp user set-role 12 author
Success: Added johndoe (12) to http://example.com as author.

wp user add-role

Adds a role for a user.

Usage

wp user add-role {user} {role}

You can specify global options and the following:

{user}
User ID, user email, or user login.
{role}
Add the specified role to the user.

Examples

$ wp user add-role 12 author
Success: Added 'author' role for johndoe (12).

wp user remove-role

Removes a user's role.

Usage

wp user remove-role {user} [{role}]

You can specify global options and the following:

{user}
User ID, user email, or user login.
[{role}]
A specific role to remove.

Examples

$ wp user remove-role 12 author
Success: Removed 'author' role for johndoe (12).

wp user add-cap

Adds a capability to a user.

Usage

wp user add-cap {user} {cap}

You can specify global options and the following:

{user}
User ID, user email, or user login.
{cap}
The capability to add.

Examples

# Add a capability for a user
$ wp user add-cap john create_premium_item
Success: Added 'create_premium_item' capability for john (16).
# Add a capability for a user
$ wp user add-cap 15 edit_product
Success: Added 'edit_product' capability for johndoe (15).

wp user remove-cap

Removes a user's capability.

Usage

wp user remove-cap {user} {cap}

You can specify global options and the following:

{user}
User ID, user email, or user login.
{cap}
The capability to be removed.

Examples

$ wp user remove-cap 11 publish_newsletters
Success: Removed 'publish_newsletters' cap for supervisor (11).
$ wp user remove-cap 11 publish_posts
Error: The 'publish_posts' cap for supervisor (11) is inherited from a role.
$ wp user remove-cap 11 nonexistent_cap
Error: No such 'nonexistent_cap' cap for supervisor (11).

wp user list-caps

Lists all capabilities for a user.

Usage

wp user list-caps {user} [--format={format}]

You can specify global options and the following:

{user}
User ID, user email, or login.
[--format={format}]

Render output in a particular format.
Default: list
Can be:

  • list
  • table
  • csv
  • json
  • count
  • yaml

Examples

$ wp user list-caps 21
edit_product
create_premium_item

wp user import-csv

Imports users from a CSV file.

If the user already exists (matching the email address or login), then the user is updated unless the --skip-update flag is used.

Usage

wp user import-csv {file} [--send-email] [--skip-update]

You can specify global options and the following:

{file}
The local or remote CSV file of users to import. If '-', then reads from STDIN.
[--send-email]
Send an email to new users with their account details.
[--skip-update]
Don't update users that already exist.

Examples

# Import users from local CSV file
$ wp user import-csv /path/to/users.csv
Success: bobjones created
Success: newuser1 created
Success: existinguser created
# Import users from remote CSV file
$ wp user import-csv http://example.com/users.csv
Sample users.csv file:
user_login,user_email,display_name,role
bobjones,bobjones@example.com,Bob Jones,contributor
newuser1,newuser1@example.com,New User,author
existinguser,existinguser@example.com,Existing User,administrator
menu

wp user reset-password

Resets the password for one or more users.

Usage

wp user reset-password {user}... [--skip-email]

You can specify global options and the following:

{user}...
one or more user logins or IDs.
[--skip-email]
Don't send an email notification to the affected user(s).

Examples

# Reset the password for two users and send them the change email.
$ wp user reset-password admin editor
Reset password for admin.
Reset password for editor.
Success: Passwords reset.

wp user spam

Marks one or more users as spam.

Usage

wp user spam {id}...

You can specify global options and the following:

{id}...
One or more IDs of users to mark as spam.

Examples

$ wp user spam 123
User 123 marked as spam.
Success: Spamed 1 of 1 users.

wp user unspam

Removes one or more users from spam.

Usage

wp user unspam {id}...

You can specify global options and the following:

{id}...
One or more IDs of users to remove from spam.

Examples

$ wp user unspam 123
User 123 removed from spam.
Success: Unspamed 1 of 1 users.

wp user check-password

Checks if a user's password is valid or not.

Usage

wp user check-password {user} {user_pass}

You can specify global options and the following:

{user}
The user login, user email or user ID of the user to check credentials for.
{user_pass}
A string that contains the plain text password for the user.

Examples

# Check whether given credentials are valid; exit status 0 if valid, otherwise 1
$ wp user check-password admin adminpass
$ echo $?
1
# Bash script for checking whether given credentials are valid or not
if ! $(wp user check-password admin adminpass); then
 notify-send "Invalid Credentials";
fi

wp user meta list

List all metadata associated with an object.

Usage

wp user meta list {id} [--keys={keys}] [--fields={fields}] [--format={format}] [--orderby={fields}] [--order={order}]

You can specify global options and the following:

{id}
ID for the object.
[--keys={keys}]
Limit output to metadata of specific keys.
[--fields={fields}]
Limit the output to specific row fields. Defaults to id,meta_key,meta_value.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • json
  • yaml
  • count
[--orderby={fields}]

Set orderby which field.
Default: id
Can be:

  • id
  • meta_key
  • meta_value
[--order={order}]

Set ascending or descending order.
Default: asc
Can be:

  • asc
  • desc
menu

wp user meta get

Get meta field value.

Usage

wp user meta get {id} {key} [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to get.
[--format={format}]

Get value in a particular format.
Default: var_export
Can be:

  • var_export
  • json
  • yaml

wp user meta delete

Delete a meta field.

Usage

wp user meta delete {id} [{key}] [{value}] [--all]

You can specify global options and the following:

{id}
The ID of the object.
[{key}]
The name of the meta field to delete.
[{value}]
The value to delete. If omitted, all rows with key will deleted.
[--all]
Delete all meta for the object.

wp user meta add

Add a meta field.

Usage

wp user meta add {id} {key} [{value}] [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to create.
[{value}]
The value of the meta field. If omitted, the value is read from STDIN.
[--format={format}]

The serialization format for the value.
Default: plaintext
Can be:

  • plaintext
  • json

wp user meta update

Update a meta field.

Usage

wp user meta update {id} {key} [{value}] [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to update.
[{value}]
The new value. If omitted, the value is read from STDIN.
[--format={format}]

The serialization format for the value.
Default: plaintext
Can be:

  • plaintext
  • json

wp user meta pluck

Get a nested value from a meta field.

Usage

wp user meta pluck {id} {key} {key-path}... [--format={format}]

You can specify global options and the following:

{id}
The ID of the object.
{key}
The name of the meta field to get.
{key-path}...
The name(s) of the keys within the value to locate the value to pluck.
[--format={format}]

The output format of the value.
--- Default: plaintext
Can be:

  • plaintext
  • json
  • yaml

wp user meta patch

Update a nested value for a meta field.

Usage

wp user meta patch {action} {id} {key} {key-path}... [{value}] [--format={format}]

You can specify global options and the following:

{action}

Patch action to perform.

Can be:

  • insert
  • update
  • delete
{id}
The ID of the object.
{key}
The name of the meta field to update.
{key-path}...
The name(s) of the keys within the value to locate the value to patch.
[{value}]
The new value. If omitted, the value is read from STDIN.
[--format={format}]

The serialization format for the value.
Default: plaintext
Can be:

  • plaintext
  • json

wp user term list

List all terms associated with an object.

Usage

wp user term list {id} {taxonomy}... [--field={field}] [--fields={fields}] [--format={format}]
{id}
ID for the object.
{taxonomy}...
One or more taxonomies to list.
[--field={field}]
Prints the value of a single field for each term.
[--fields={fields}]
Limit the output to specific row fields.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • json
  • yaml
  • count
  • ids

Available fields

These fields will be displayed by default for each term:

  • term_id
  • name
  • slug
  • taxonomy

These fields are optionally available:

  • term_taxonomy_id
  • description
  • term_group
  • parent
  • count
menu

wp user term remove

Remove a term from an object.

Usage

wp user term remove {id} {taxonomy} [{term}...] [--by={field}] [--all]

You can specify global options and the following:

{id}
The ID of the object.
{taxonomy}
The name of the term's taxonomy.
[{term}...]
The name of the term or terms to be removed from the object.
[--by={field}]

Explicitly handle the term value as a slug or id.

Can be:

  • slug
  • id
[--all]
Remove all terms from the object.

wp user term add

Add a term to an object.

Append the term to the existing set of terms on the object.

Usage

wp user term add {id} {taxonomy} {term}... [--by={field}]
{id}
The ID of the object.
{taxonomy}
The name of the taxonomy type to be added.
{term}...
The slug of the term or terms to be added.
[--by={field}]

Explicitly handle the term value as a slug or id.

Can be:

  • slug
  • id

wp user term set

Set object terms.

Replaces existing terms on the object.

Usage

wp user term set {id} {taxonomy} {term}... [--by={field}]
{id}
The ID of the object.
{taxonomy}
The name of the taxonomy type to be updated.
{term}...
The slug of the term or terms to be updated.
[--by={field}]

Explicitly handle the term value as a slug or id.

Can be:

  • slug
  • id

wp user session destroy

Destroy a session for the given user.

Usage

wp user session destroy {user} [{token}] [--all]

You can specify global options and the following:

{user}
User ID, user email, or user login.
[{token}]
The token of the session to destroy. Defaults to the most recently created session.
[--all]
Destroy all of the user's sessions.

Examples

# Destroy the most recent session of the given user.
$ wp user session destroy admin
Success: Destroyed session. 3 sessions remaining.
# Destroy a specific session of the given user.
$ wp user session destroy admin e073ad8540a9c2...
Success: Destroyed session. 2 sessions remaining.
# Destroy all the sessions of the given user.
$ wp user session destroy admin --all
Success: Destroyed all sessions.
# Destroy all sessions for all users.
$ wp user list --field=ID | xargs -n 1 wp user session destroy --all
Success: Destroyed all sessions.
Success: Destroyed all sessions.
menu

wp user session list

List sessions for the given user.

Note: The token field does not return the actual token, but a hash of it. The real token is not persisted and can only be found in the corresponding cookies on the client side.

Usage

wp user session list {user} [--fields={fields}] [--format={format}]

You can specify global options and the following:

{user}
User ID, user email, or user login.
[--fields={fields}]
Limit the output to specific fields.
[--format={format}]

Render output in a particular format.
Default: table
Can be:

  • table
  • csv
  • json
  • yaml
  • count
  • ids

Available fields

These fields will be displayed by default for each session:

  • token
  • login_time
  • expiration_time
  • ip
  • ua

These fields are optionally available:

  • expiration
  • login

Examples

# List a user's sessions.
$ wp user session list admin@example.com --format=csv
login_time,expiration_time,ip,ua
"2016-01-01 12:34:56","2016-02-01 12:34:56",127.0.0.1,"Mozilla/5.0..."