Skip to main content

wp role list

Overview

List every role registered in WordPress — including core roles and any custom roles added by plugins or themes. Use this to discover valid role slugs before assigning them to users or auditing access control.

What It Does​

wp role list reads from the wp_user_roles option and outputs all registered role objects. This includes the display name, slug, and optionally all capabilities assigned to each role.

Syntax​

wp role list [OPTIONS]

Arguments & Options​

FlagDescription
--fields=FIELDSFields to display: name, role
--field=FIELDOutput a single field per line
--format=FORMATOutput format: table, json, csv, yaml

Basic Usage​

List all roles​

wp role list

Output:

+---------------+---------------------+
| name          | role                |
+---------------+---------------------+
| Administrator | administrator       |
| Editor        | editor              |
| Author        | author              |
| Contributor   | contributor         |
| Subscriber    | subscriber          |
| Shop Manager  | shop_manager        |
+---------------+---------------------+

Get role slugs only (for scripting)​

wp role list --field=role

Export as JSON​

wp role list --format=json

Real-World Scenarios​

Scenario 1: Verify a role exists before assigning​

if wp role list --field=role | grep -q "^custom_reviewer$"; then
  wp user set-role john custom_reviewer
else
  echo "Role does not exist — create it first with wp role create"
fi

Scenario 2: Audit all registered roles after plugin install​

echo "=== Roles Before ==="
wp role list --field=role | sort > before.txt

# Install plugin...
wp plugin install custom-roles-plugin --activate

echo "=== Roles After ==="
wp role list --field=role | sort > after.txt

diff before.txt after.txt

Quick Reference​

wp role list                     # All roles (table)
wp role list --field=role        # Slugs only
wp role list --format=json       # JSON output

Next Steps​