wp-cli/role-command

Adds, removes, lists, and resets roles and capabilities.

wp-cli/role-command

Adds, removes, lists, and resets roles and capabilities., _(*1)

, _(*2)

Quick links: Using | Installing | Contributing | Support, _(*3)

Using

This package implements the following commands:, _(*4)

wp role

Manages user roles, including creating new roles and resetting to defaults., _(*5)

wp role

See references for Roles and Capabilities and WP User class., _(*6)

EXAMPLES, _(*7)

# List roles.
$ wp role list --fields=role --format=csv
role
administrator
editor
author
contributor
subscriber

# Check to see if a role exists.
$ wp role exists editor
Success: Role with ID 'editor' exists.

# Create a new role.
$ wp role create approver Approver
Success: Role with key 'approver' created.

# Delete an existing role.
$ wp role delete approver
Success: Role with key 'approver' deleted.

# Reset existing roles to their default capabilities.
$ wp role reset administrator author contributor
Success: Reset 3/3 roles.

wp role create

Creates a new role., _(*8)

wp role create <role-key> <role-name> [--clone=<role>]

OPTIONS, _(*9)

<role-key>
    The internal name of the role.

<role-name>
    The publicly visible name of the role.

[--clone=<role>]
    Clone capabilities from an existing role.

EXAMPLES, _(*10)

# Create role for Approver.
$ wp role create approver Approver
Success: Role with key 'approver' created.

# Create role for Product Administrator.
$ wp role create productadmin "Product Administrator"
Success: Role with key 'productadmin' created.

wp role delete

Deletes an existing role., _(*11)

wp role delete <role-key>

OPTIONS, _(*12)

<role-key>
    The internal name of the role.

EXAMPLES, _(*13)

# Delete approver role.
$ wp role delete approver
Success: Role with key 'approver' deleted.

# Delete productadmin role.
wp role delete productadmin
Success: Role with key 'productadmin' deleted.

wp role exists

Checks if a role exists., _(*14)

wp role exists <role-key>

Exits with return code 0 if the role exists, 1 if it does not., _(*15)

OPTIONS, _(*16)

<role-key>
    The internal name of the role.

EXAMPLES, _(*17)

# Check if a role exists.
$ wp role exists editor
Success: Role with ID 'editor' exists.

wp role list

Lists all roles., _(*18)

wp role list [--fields=<fields>] [--field=<field>] [--format=<format>]

OPTIONS, _(*19)

[--fields=<fields>]
    Limit the output to specific object fields.

[--field=<field>]
    Prints the value of a single field.

[--format=<format>]
    Render output in a particular format.
    ---
    default: table
    options:
      - table
      - csv
      - json
      - count
      - yaml
    ---

AVAILABLE FIELDS, _(*20)

These fields will be displayed by default for each role:, _(*21)

• name
• role

There are no optional fields., _(*22)

EXAMPLES, _(*23)

# List roles.
$ wp role list --fields=role --format=csv
role
administrator
editor
author
contributor
subscriber

wp role reset

Resets any default role to default capabilities., _(*24)

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

Uses WordPress' populate_roles() function to put one or more roles back into the state they were at in the a fresh WordPress install. Removes any capabilities that were added, and restores any capabilities that were removed. Custom roles are not affected., _(*25)

OPTIONS, _(*26)

[<role-key>...]
    The internal name of one or more roles to reset.

[--all]
    If set, all default roles will be reset.

EXAMPLES, _(*27)

# Reset three roles.
$ wp role reset administrator author contributor
Restored 1 capability to and removed 0 capabilities from 'administrator' role.
No changes necessary for 'author' role.
No changes necessary for 'contributor' role.
Success: 1 of 3 roles reset.

# Reset a custom role.
$ wp role reset custom_role
Custom role 'custom_role' not affected.
Error: Must specify a default role to reset.

# Reset all default roles.
$ wp role reset --all
Success: All default roles reset.

wp cap

Adds, removes, and lists capabilities of a user role., _(*28)

wp cap

See references for Roles and Capabilities and WP User class., _(*29)

EXAMPLES, _(*30)

# Add 'spectate' capability to 'author' role.
$ wp cap add 'author' 'spectate'
Success: Added 1 capability to 'author' role.

# Add all caps from 'editor' role to 'author' role.
$ wp cap list 'editor' | xargs wp cap add 'author'
Success: Added 24 capabilities to 'author' role.

# Remove all caps from 'editor' role that also appear in 'author' role.
$ wp cap list 'author' | xargs wp cap remove 'editor'
Success: Removed 34 capabilities from 'editor' role.

wp cap add

Adds capabilities to a given role., _(*31)

wp cap add <role> <cap>... [--grant]

OPTIONS, _(*32)

<role>
    Key for the role.

<cap>...
    One or more capabilities to add.

[--grant]
    Adds the capability as an explicit boolean value, instead of implicitly defaulting to `true`.
    ---
    default: true
    options:
      - true
      - false
    ---

EXAMPLES, _(*33)

# Add 'spectate' capability to 'author' role.
$ wp cap add author spectate
Success: Added 1 capability to 'author' role.

wp cap list

Lists capabilities for a given role., _(*34)

wp cap list <role> [--format=<format>] [--show-grant]

OPTIONS, _(*35)

<role>
    Key for the role.

[--format=<format>]
    Render output in a particular format.
    ---
    default: list
    options:
      - list
      - table
      - csv
      - json
      - count
      - yaml
    ---

[--show-grant]
    Display all capabilities defined for a role including grant.
    ---
    default: false
    ---

EXAMPLES, _(*36)

# Display alphabetical list of Contributor capabilities.
$ wp cap list 'contributor' | sort
delete_posts
edit_posts
level_0
level_1
read

wp cap remove

Removes capabilities from a given role., _(*37)

wp cap remove <role> <cap>...

OPTIONS, _(*38)

<role>
    Key for the role.

<cap>...
    One or more capabilities to remove.

EXAMPLES, _(*39)

# Remove 'spectate' capability from 'author' role.
$ wp cap remove author spectate
Success: Removed 1 capability from 'author' role.

Installing

This package is included with WP-CLI itself, no additional installation necessary., _(*40)

To install the latest version of this package over what's included in WP-CLI, run:, _(*41)

wp package install git@github.com:wp-cli/role-command.git

Contributing

We appreciate you taking the initiative to contribute to this project., _(*42)

Contributing isn’t limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation., _(*43)

For a more thorough introduction, check out WP-CLI's guide to contributing. This package follows those policy and guidelines., _(*44)

Reporting a bug

Think you’ve found a bug? We’d love for you to help us get it fixed., _(*45)

Before you create a new issue, you should search existing issues to see if there’s an existing resolution to it, or if it’s already been fixed in a newer version., _(*46)

Once you’ve done a bit of searching and discovered there isn’t an open or fixed issue for your bug, please create a new issue. Include as much detail as you can, and clear steps to reproduce if possible. For more guidance, review our bug report documentation., _(*47)

Creating a pull request

Want to contribute a new feature? Please first open a new issue to discuss whether the feature is a good fit for the project., _(*48)

Once you've decided to commit the time to seeing your pull request through, please follow our guidelines for creating a pull request to make sure it's a pleasant experience. See "Setting up" for details specific to working on this package locally., _(*49)

Support

GitHub issues aren't for general support questions, but there are other venues you can try: https://wp-cli.org/#support, _(*50)

This README.md is generated dynamically from the project's codebase using wp scaffold package-readme (doc). To suggest changes, please submit a pull request against the corresponding part of the codebase., _(*51)