WordPress at a glance
Home Handbook WP-CLI Commands

wp role

Manages user roles, including creating new roles and resetting to defaults.

See also wp cap command.

Commands Description
Lists all roles.
Checks if a role exists.
Creates a new role.
Deletes an existing role.
Resets any default role to default capabilities.

Examples

# List roles.
$ wp role list --fields=role --format=csv
role
administrator
editor
author
contributor
subscriber

# Check to see if a role exists.
$ wp role exists editor
Success: Role with ID 'editor' exists.

# Create a new role.
$ wp role create approver Approver
Success: Role with key 'approver' created.

# Delete an existing role.
$ wp role delete approver
Success: Role with key 'approver' deleted.

# Reset existing roles to their default capabilities.
$ wp role reset administrator author contributor
Success: Reset 3/3 roles.

Source code of the commands


wp role list

Lists all roles.

Usage

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

You can specify global options and the following:

[--fields={fields}]
Limit the output to specific object fields.
[--field={field}]
Prints the value of a single field.
[--format={format}]

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

  • table
  • csv
  • json
  • count
  • yaml

Available fields

These fields will be displayed by default for each role:

  • name
  • role

There are no optional fields.

Examples

# List roles.
$ wp role list --fields=role --format=csv
role
administrator
editor
author
contributor
subscriber

wp role exists

Checks if a role exists.

Exits with return code 0 if the role exists, 1 if it does not.

Usage

wp role exists {role-key}

You can specify global options and the following:

{role-key}
The internal name of the role.

Examples

# Check if a role exists.
$ wp role exists editor
Success: Role with ID 'editor' exists.

wp role create

Creates a new role.

Usage

wp role create {role-key} {role-name} [--clone={role}]

You can specify global options and the following:

{role-key}
The internal name of the role.
{role-name}
The publicly visible name of the role.
[--clone={role}]
Clone capabilities from an existing role.

Examples

# Create role for Approver.
$ wp role create approver Approver
Success: Role with key 'approver' created.
# Create role for Product Administrator.
$ wp role create productadmin "Product Administrator"
Success: Role with key 'productadmin' created.

wp role delete

Deletes an existing role.

Usage

wp role delete {role-key}

You can specify global options and the following:

{role-key}
The internal name of the role.

Examples

# Delete approver role.
$ wp role delete approver
Success: Role with key 'approver' deleted.
# Delete productadmin role.
wp role delete productadmin
Success: Role with key 'productadmin' deleted.

wp role reset

Resets any default role to default capabilities.

Usage

wp role reset [{role-key}...] [--all]

You can specify global options and the following:

[{role-key}...]
The internal name of one or more roles to reset.
[--all]
If set, all default roles will be reset.

Examples

# Reset role.
$ wp role reset administrator author contributor
Success: Reset 1/3 roles.
# Reset all default roles.
$ wp role reset --all
Success: All default roles reset.