WordPress at Your Fingertips

wp user

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

Commands Description
wp user list Lists users.
wp user get Gets details about a user.
wp user delete Deletes one or more users from the current site.
wp user create Creates a new user.
wp user update Updates an existing user.
wp user generate Generates some users.
wp user set-role Sets the user role.
wp user add-role Adds a role for a user.
wp user remove-role Removes a user's role.
wp user add-cap Adds a capability to a user.
wp user remove-cap Removes a user's capability.
wp user list-caps Lists all capabilities for a user.
wp user import-csv Imports users from a CSV file.
wp user reset-password Resets the password for one or more users.
wp user spam Marks one or more users as spam.
wp user unspam Removes one or more users from spam.
wp user check-password Checks if a user's password is valid or not.
wp user meta list List all metadata associated with an object.
wp user meta get Get meta field value.
wp user meta delete Delete a meta field.
wp user meta add Add a meta field.
wp user meta update Update a meta field.
wp user meta pluck Get a nested value from a meta field.
wp user meta patch Update a nested value for a meta field.
wp user term list List all terms associated with an object.
wp user term remove Remove a term from an object.
wp user term add Add a term to an object.
wp user term set Set object terms.
wp user session destroy Destroy a session for the given user.
wp user session list 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..."