wp role reset

Overview

Restore one or all built-in WordPress roles to their factory-default capabilities. Use this to undo accidental permission changes caused by plugins or manual edits.

What It Does

wp role reset calls populate_roles() for the specified roles, re-adding all default capabilities and removing any additions or subtractions made after initial setup.

Syntax

wp role reset [<role>...] [--all]

Arguments & Options

Argument / Flag	Description
ROLE...	One or more built-in role slugs to reset
--all	Reset all built-in roles simultaneously

Built-in roles only

wp role reset only works for WordPress's built-in roles: administrator, editor, author, contributor, subscriber. Custom roles cannot be reset.

Basic Usage

Reset the editor role

wp role reset editor

Reset all built-in roles at once

wp role reset --all

Reset multiple specific roles

wp role reset contributor author

Real-World Scenarios

Scenario 1: After a plugin corrupted capabilities

# Verify editor is missing expected capabilities
wp cap list editor --format=table | grep publish_posts

# Reset to defaults
wp role reset editor

# Verify restored
wp cap list editor --format=table | grep publish_posts

Scenario 2: Post-migration cleanup

# After importing from another site, reset all roles to clean state
wp role reset --all
echo "All built-in roles restored to WordPress defaults."

Best Practices

1. Back up with wp cap list (output to file) before resetting — so you can see what changed.
2. Do not reset if a plugin depends on modified roles — the plugin may re-add its capabilities, but manual additions will be lost.
3. Use on staging first before resetting roles on production.

Troubleshooting

Problem	Cause	Fix
Error: Role not found	Typo or custom role provided	Use wp role list --field=role to confirm the slug
Capabilities return but plugin features broken	Plugin manages its own caps separately	Re-activate the plugin or re-install it

Quick Reference

wp role reset editor              # Reset one role
wp role reset --all               # Reset all built-in roles
wp cap list editor --format=table # Verify capabilities after reset

Next Steps

• wp cap list — audit capabilities before/after reset.
• wp cap add — re-add custom capabilities after reset.
• wp role list — view all registered roles.