cwp roles

cwp roles [flags]

cwp roles groups the commands below and takes no action of its own; run it alone and it prints its help.

Flag	What it does	Default
--with-agent	with —dry-run on a host with no shell: install and remove the PHP agent so the plan is real	off

Subcommand	What it does
cwp roles pull	Write roles.yml from what a site grants (read-only against the site)
cwp roles push	Create roles and grant capabilities to match roles.yml

What it does

Carries the roles a site defines and what each one may do, as roles.yml in the project root.

A custom role lives in exactly one option and travelled through nothing. A repository checked out on a second machine built a site with five roles where the first had seven, and no check said so. pull records what a site grants; push makes another site match.

version: 1
roles:
  sos_organizer:
    name: Organizer
    capabilities:
      - create_sos_events
      - publish_sos_events
      - read

A map keyed by slug, sorted throughout. A diff on one changed capability therefore shows which role it belongs to, and a pull never reorders the file.

Why it is not a settings group

Roles are one option, and cwp settings could carry it. Three reasons it does not:

1. It is a table, not a value. Seven roles times ninety capabilities is one enormous value as a setting, and a matrix a reviewer can read down as a file.
2. The database prefix is in the key. wp_user_roles on one site, wp_abc_user_roles on another. An allowlist naming it is a file that does not port.
3. It is a permission boundary. A change here is the one settings change where “somebody edited a value” and “somebody granted themselves an ability” look identical in a diff. It earns its own file, its own drift row and its own confirmation.

What it does not do

• It records no user. The file says what a role can do, never who holds it.
• It never narrows a site by default. The pull reports a capability the site grants and the file does not describe; --prune on the push removes one.
• It does not pin WordPress’s own roles. Core adds capabilities in a release, and a file that fought every update would be a file nobody trusts.