wp role create

Overview

Define a brand-new custom role in WordPress. Custom roles are stored in the wp_options table and persist across WordPress updates.

What It Does

wp role create calls add_role() to register a new role with a given display name. Capabilities are empty by default — you add them separately with wp cap add.

Syntax

wp role create <role-slug> <role-name>

Basic Usage

Create a basic custom role

wp role create content_reviewer "Content Reviewer"

Create and immediately add capabilities

wp role create content_reviewer "Content Reviewer"
wp cap add content_reviewer read
wp cap add content_reviewer edit_posts

Real-World Scenarios

Scenario 1: Create a read-only auditor role

wp role create site_auditor "Site Auditor"
wp cap add site_auditor read
wp cap add site_auditor list_users

Scenario 2: Create a limited WooCommerce role

wp role create store_viewer "Store Viewer"
wp cap add store_viewer read
wp cap add store_viewer view_woocommerce_reports

Best Practices

1. Use lowercase_with_underscores for the slug — WordPress convention.
2. Always add capabilities after creation — the new role has none by default.
3. Document custom roles your project adds — they can confuse future administrators.

Troubleshooting

Problem	Cause	Fix
Error: Role with that key already exists	Duplicate slug	Use wp role list to check
Role disappears after update	Added by a plugin that was deactivated	Use wp role create after plugin install instead

Quick Reference

wp role create <slug> "<Display Name>"   # Create role
wp cap add <slug> <capability>           # Assign capabilities
wp role list                             # Verify creation

Next Steps

• wp cap add — add capabilities to the new role.
• wp role delete — remove the role if no longer needed.
• wp role reset — reset a role to defaults.