Contents

WP-CLI commands - Plugixa Advanced User Role Editor

The plugin adds four commands to WP-CLI under wp plugixa-aure. One of them writes: rescue, the way back in when nobody can reach the editor. The other three only read, and answer questions you would otherwise open a screen for.

Command What it does Writes
wp plugixa-aure rescue <user> Prints a one-time link that gives an account the Administrator role back Yes, when the link is opened
wp plugixa-aure explain <user> <capability> [<object>] Says whether a person holds a capability, and why No
wp plugixa-aure roles Lists every role with its permission and people counts No
wp plugixa-aure orphans Lists capabilities that roles hold and nothing on the site registers No

The commands exist only when the plugin is active and WordPress is running under WP-CLI. They are part of the free edition.

Who can run them

WP-CLI runs as the shell user. There is no signed-in WordPress account, so the commands make no permission check: anyone who can run wp on the server can run them. That is the point of rescue, which has to work when every account has lost its access.

For the same reason, the read commands report on any account you name. Treat shell access to the site as you would an administrator account.

There is no command that edits a role

This is deliberate. Every safety guardrail compares a change with what the person making it holds, and on the command line there is no such person. A command that changed permissions would have to skip those rules, so the plugin does not ship one.

To change roles from a script, use the REST API with an account that holds the right permissions. The guardrails apply there in full.

Naming a user

rescue and explain take a user as their first argument. It can be:

  • a user ID, such as 12,
  • a login, such as maria,
  • an email address.

A value made only of digits is read as an ID. Anything else is tried as a login first, then as an email address.

Message Cause
“Give a user ID, login or email.” The argument was left out
“No user matches “maria”.” No account has that ID, login or email

rescue

wp plugixa-aure rescue <user>

Prints a recovery link for one account, with the account’s login and ID above it. The link:

  • is valid for 15 minutes;
  • works once;
  • works only while signed in as that user;
  • gives the account the Administrator role;
  • is recorded in History like any other change.

Running the command changes nothing by itself. The role is given when the link is opened. If the link cannot be made, the command stops with “Could not issue a link for that user.”

When to use it, and the messages you may meet when opening a link, are covered in Safety guardrails and Troubleshooting.

explain

wp plugixa-aure explain <user> <capability> [<object>]

Answers one question: can this person do this, and what decided it. It is the command-line counterpart of Check access, for a support engineer who has SSH access and no dashboard login. It reads the account’s saved roles and permissions and changes nothing.

Argument Required What it is
<user> Yes A user ID, login or email
<capability> Yes A WordPress capability name, such as edit_others_posts or edit_post
<object> No The ID of the item the question is about, such as a post ID for edit_post

Check access asks in plain words (“Edit a specific post”). This command takes the capability name itself. The name is lower-cased and stripped of anything that is not a letter, digit, underscore or hyphen before it is checked, and <object> is read as a whole number.

wp plugixa-aure explain maria edit_post 41

What it prints

Line Meaning
The first line The login and ID, then ALLOWED or REFUSED
Roles: The account’s roles in the order it holds them, or (none)
Needs: The capabilities WordPress actually requires for this question
One line per step [layer/effect] followed by a sentence explaining that step

ALLOWED or REFUSED is WordPress’s own answer for that account, not the plugin’s opinion. Needs: matters for questions about one item: edit_post on somebody else’s published post becomes edit_others_posts and edit_published_posts, and those are the capabilities to grant.

Each step names a layer and an effect.

Layer What it covers
super_admin On multisite, the account is a network super administrator, which allows everything whatever its roles say
meta_cap WordPress turned the capability you asked about into the ones listed under Needs:, or refuses it outright
role One of the account’s roles allows or blocks the capability, or no role mentions it
user The capability is allowed or blocked on the account itself, which comes after every role
filter Other code changed the answer. See below
Effect Meaning
grant This step allows it
deny This step blocks it
absent No role the account holds mentions the capability, so it is not granted
rewrite The capability was turned into others

When two roles disagree, the step for the earlier role says that it does not decide the answer, and names the later role or the account setting that does.

When roles do not explain the answer

If the roles and the account’s own permissions point one way and WordPress answers the other, the command adds a filter step and ends with a warning that something is filtering user_has_cap. That is another plugin, the theme, or code in the site itself, granting or blocking the capability as the request runs. The command reports that this happened. It cannot say which code did it.

Messages

Message Cause
“Give a capability to check.” The second argument was left out, or held no usable characters
“Give a user ID, login or email.” The first argument was left out

roles

wp plugixa-aure roles

Prints a table of every role on the site. It takes no arguments.

Column Meaning
slug The role’s slug
name The role’s name
granted How many permissions the role allows
denied How many permissions the role blocks
holders How many people have the role. - when head counts are switched off with the plugixa_aure_count_role_users filter
editable yes or no. Administrator is no unless editing it is switched on in Settings

The screen with the same information is Roles.

orphans

wp plugixa-aure orphans

Lists every capability that at least one role holds and that nothing on the site registers. These are usually left behind by a plugin that has been removed. A capability that belongs to a plugin which is installed but switched off is listed too, because nothing registers it while the plugin is off. Check what a capability belonged to before removing it.

Column Meaning
capability The capability name
severity The plugin’s risk rating for it: critical, high, medium or none
held_by The roles that hold it

When there is nothing to list, the command prints a success line saying that every capability a role holds is registered by something on the site.

The command only lists. To remove a leftover from every role, use Unknown source on the All permissions screen.

Using the commands in a script

The three read commands print text and tables meant for a person to read. They take no --format option, so a script that needs structured data is better served by the REST API, where /roles, /capabilities/orphans and /simulate return the same information as JSON.

What to do next

Quick Links

Plugin page Changelog