Skip to main content

wp role delete

Overview

Permanently remove a custom role from WordPress. Users assigned to that role are not deleted, but they lose the role and its capabilities.

What It Does​

wp role delete calls remove_role() to unregister the role from WordPress. It does not delete users assigned to that role — they simply become role-less until reassigned.

Syntax​

wp role delete <role>

Basic Usage​

Delete a custom role​

wp role delete content_reviewer

Output:

Success: Role with key 'content_reviewer' deleted.

Real-World Scenarios​

Scenario 1: Clean up before deleting a role​

# 1. Find all users with this role
wp user list --role=content_reviewer --fields=ID,user_login

# 2. Reassign them to a standard role
for user in $(wp user list --role=content_reviewer --field=user_login); do
  wp user set-role "$user" editor
done

# 3. Delete the custom role
wp role delete content_reviewer

Scenario 2: Remove deprecated roles from old plugins​

for role in old_role_1 old_role_2; do
  if wp role list --field=role | grep -q "^${role}$"; then
    wp role delete "$role"
    echo "Deleted: $role"
  fi
done

Best Practices​

Reassign users before deleting

Users assigned only to the deleted role will have no role after deletion. They can still log in but will have no capabilities.

  1. Always check for users on the role before deleting it.
  2. Reassign affected users with wp user set-role before removing the role.

Quick Reference​

wp user list --role=<slug>           # Check who uses the role
wp user set-role <user> editor       # Reassign users
wp role delete <slug>                # Delete the role
wp role list                         # Verify removal

Next Steps​