Hooks, REST API and WP-CLI

Filters

Filter	What it's for
roleline_capability_group	The group a capability is listed in ($group, $cap). Return a new key and give it a label with roleline_capability_group_labels
roleline_capability_group_labels	Group labels (key => label)
roleline_capability_descriptions	Descriptions (capability => text), e.g. for your plugin's capabilities
roleline_required_capabilities	What nobody can take away from themselves (default roleline_manage_roles, promote_users, edit_users, list_users)
roleline_protected_capabilities	The Administrator role's capabilities whose removal needs a confirmation (WordPress's defaults)
roleline_risky_capabilities	Capabilities whose granting to a role needs a confirmation
roleline_unrestricted	Whether a user may grant capabilities they don't have ($unrestricted, $user_id; default: super admins on multisite, else manage_options)
roleline_assignable_roles	Roles the current user may give users or take away (slug => name)
roleline_backups_keep	How many backups are kept (50)
roleline_delete_role_limit	How many users a role may have to be deleted on Users → Roles or with the REST API (1000); bigger roles are deleted with wp roleline delete
roleline_admin_tabs	Tabs on Users → Roles (key => label); print one with the roleline_admin_tab_{key} action
roleline_roles_columns	Columns of the roles list; print one with roleline_roles_column ($column, $slug)

Describing your plugin's capabilities and grouping them:

add_filter( 'roleline_capability_descriptions', function ( $descriptions ) {
	$descriptions['view_reports'] = 'See the sales reports.';
	return $descriptions;
} );

add_filter( 'roleline_capability_group', function ( $group, $cap ) {
	return 0 === strpos( $cap, 'acme_' ) ? 'acme' : $group;
}, 10, 2 );
add_filter( 'roleline_capability_group_labels', function ( $labels ) {
	return $labels + array( 'acme' => 'Acme Reports' );
} );

Actions

Action	When
roleline_loaded	Roleline has loaded (on plugins_loaded). Add-ons hook their features here
roleline_before_roles_change	Before a change is saved, after the backup ($label, $old_roles, $new_roles)
roleline_roles_changed	After a change is saved ($label, $old_roles, $new_roles)
roleline_role_deleted	A role was deleted and its users moved ($slug, $reassign, $user_ids)
roleline_capability_deleted	An unused capability was deleted ($cap)
roleline_backup_created / roleline_backup_restored	A backup was made ($id, $label) / restored ($id)
roleline_user_roles_changed	A user's roles changed through Roleline ($user_id, $added, $removed)
roleline_user_role_after	Prints after a role on a user's profile ($user, $slug, $has, $allowed)
roleline_editor_sidebar	Prints below Save on the role editor ($role)
roleline_admin_load / roleline_admin_notices	Users → Roles is loading ($tab) / prints its notices

Logging every change:

add_action( 'roleline_roles_changed', function ( $label, $old, $new ) {
	error_log( 'Roles changed by ' . wp_get_current_user()->user_login . ': ' . $label );
}, 10, 3 );

PHP API

Extendiment\Roleline\Roles (create(), update(), delete(), reset(), set_default(), commit()), Users (set_roles(), add_role(), remove_role(), assignable()), Backups (create(), all(), restore(), compare()) and Capabilities (all(), grouped(), add_custom(), delete()) are public. Changes return true or a WP_Error: roleline_blocked (refused; reasons in errors) or roleline_confirm (send again with array( 'confirm' => true )).

REST API

Namespace roleline/v1, for users with roleline_manage_roles (a user's roles: for whoever may promote that user). Authenticate as usual (cookie and nonce, or application passwords).

Route	Methods
/roles	GET list, POST create (name, slug, copy_from)
/roles/{role}	GET, POST/PUT/PATCH (name, capabilities as the full set, or add / remove), DELETE (reassign)
/roles/{role}/preview	POST: what a change would do, with errors and warnings, without saving
/roles/{role}/reset	POST
/default-role	POST (role)
/capabilities	GET grouped, POST add (name)
/capabilities/{cap}	DELETE (unused ones)
/backups	GET, POST (label)
/backups/{id}	GET: compared with now
/backups/{id}/restore	POST
/export	GET (roles[])
/import	POST (data, roles[], dry_run)
/users/{id}/roles	GET, PUT (roles[])

A refused change answers 403 with errors; a risky one 409 with warnings until it's sent again with "confirm": true.

curl -u admin:APP_PASSWORD -X POST https://example.com/wp-json/roleline/v1/roles/support_agent \
  -H 'Content-Type: application/json' -d '{"add":["moderate_comments"]}'

WP-CLI

Command	What it does
wp roleline list	Roles with users and capability counts
wp roleline delete <role> [--reassign=<role>] [--yes]	Deletes a role of any size, without checks; users without another role get --reassign
wp roleline backups	The backups, newest first
wp roleline backup [--label=…]	Backs up now
wp roleline restore [<id>] [--yes]	Restores a backup (the latest by default), without checks
wp roleline reset <role>… [--all] [--yes]	Resets WordPress's roles to their defaults
wp roleline repair [--user=…]	Puts the Administrator role's capabilities back; optionally makes a user an administrator
wp roleline export [<file>] [--roles=…]	Exports roles as JSON
wp roleline import <file> [--yes]	Imports roles from a file