WordPress at Your Fingertips

wp role

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

See also wp cap command.

Commands Description
wp role list Lists all roles.
wp role exists Checks if a role exists.
wp role create Creates a new role.
wp role delete Deletes an existing role.
wp role reset 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.