wp user set-role

Overview

Replace a user's primary role with a new one. Unlike add-role, this removes all current roles first and assigns only the specified one — enforcing single-role access policies.

What It Does

wp user set-role calls WP_User::set_role() — which removes all existing roles and assigns the new one. Use this for clean role transitions.

Syntax

wp user set-role <user> <role>

Arguments

Argument	Description
USER	User ID, login, or email
ROLE	Target role slug (e.g. editor, administrator)

Basic Usage

Promote a subscriber to author

wp user set-role john author

Demote an admin to editor

wp user set-role 14 editor

Set role by email

wp user set-role sarah@example.com contributor

Real-World Scenarios

Scenario 1: Standardize all contributors to authors

for user in $(wp user list --role=contributor --field=user_login); do
  wp user set-role "$user" author
  echo "Promoted $user → author"
done

Scenario 2: Demote all admins except ID 1 to editor

for id in $(wp user list --role=administrator --field=ID); do
  if [[ "$id" != "1" ]]; then
    wp user set-role "$id" editor
    echo "Demoted user $id → editor"
  fi
done

Scenario 3: Onboarding workflow — set role after profile review

USERS=("alice" "bob" "carol")
for user in "${USERS[@]}"; do
  wp user set-role "$user" author
done

set-role vs add-role vs remove-role

Command	Effect
set-role	Replaces all current roles with the new one
add-role	Adds an additional role (multisite or custom)
remove-role	Removes a specific role, leaving others intact

Best Practices

1. Use set-role for single-role sites — it ensures a clean, predictable role state.
2. Use add-role on WooCommerce/multisite where users may have secondary roles.
3. Verify the role exists with wp role list before setting it in a script.

Troubleshooting

Problem	Cause	Fix
Error: Invalid role	Typo or role not registered	Run wp role list to verify slug
User still has old capabilities	Cached capabilities	Run wp cache flush

Quick Reference

wp user set-role <user> <role>           # Set role
wp user set-role 14 editor               # By ID
wp user set-role john administrator      # Promote to admin

Next Steps

• wp user add-role — add a secondary role without removing existing ones.
• wp user remove-role — remove one role from a multi-role user.
• wp role list — list all available roles.