wp cap add

Overview

Assign one or more capabilities to any WordPress role — including custom roles. Changes persist in the database and take effect immediately for all users with that role.

What It Does

wp cap add calls WP_Role::add_cap() for each specified capability, marking it as true in the role's capabilities array in wp_user_roles.

Syntax

wp cap add <role> <cap>...

Basic Usage

Grant a single capability

wp cap add editor manage_options

Grant multiple capabilities at once

wp cap add content_reviewer read edit_posts

Real-World Scenarios

Scenario 1: Give editors plugin management rights

wp cap add editor install_plugins activate_plugins

Scenario 2: Configure a custom read-only auditor role

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

Scenario 3: Batch-add capabilities from a list

CAPS="read edit_posts edit_published_posts publish_posts"
for cap in $CAPS; do
  wp cap add author_plus "$cap"
done

Common WordPress Capabilities

Capability	Grants Access To
read	Read private pages/posts
edit_posts	Edit own posts
publish_posts	Publish posts
edit_others_posts	Edit any post
manage_options	WordPress Settings page (admin panel)
manage_categories	Add/delete categories
upload_files	Media library uploads
install_plugins	Install plugins
manage_woocommerce	WooCommerce admin

Best Practices

1. Document capability grants — track what you've added so they can be audited or removed.
2. Avoid granting manage_options to non-admin roles without careful review.
3. Use custom roles rather than adding sensitive caps to built-in ones.

Quick Reference

wp cap add <role> <capability>              # Add one cap
wp cap add <role> cap1 cap2 cap3           # Add multiple
wp cap list <role> --allowed               # Verify additions

Next Steps

• wp cap remove — revoke a capability.
• wp cap list — audit current capabilities.
• wp role create — create a custom role to add capabilities to.