--- title: "openemail roles" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/roles" area: "CLI" category: "Reference" --- # openemail roles Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail roles list` List every role in the workspace ```bash openemail roles list [flags] ``` Resolves one page of the roles the workspace defines. The seeded roles come first in ladder order (Owner, Admin, Member, Viewer, Developer, Billing) and custom roles follow alphabetically. The order is read from `builtin`, so a renamed seeded role keeps its place. A workspace older than roles has no role rows, and the first read seeds them instead of returning an empty list. Seeding runs once per workspace, and afterwards only the owner role is ever restored, so a seeded role you delete stays deleted. Each row carries `members` and `apiKeys` counts computed at read time. A role is a ceiling for the keys issued under it. What a key may do is its own scopes intersected with its role's permissions, resolved on every request, so a key holding `emails:send` under a role without it cannot send. A key with no role has no ceiling. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `roles:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page. Leave it out for the first page. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail roles list ``` Walk every page and stop after 100 items ```bash openemail roles list --all --max 100 ``` One JSON object per line when piped ```bash openemail roles list --all > roles.ndjson ``` Also available in: API [`GET /roles`](https://openemail.uk/docs/api/reference/roles#get-roles); SDK [`roles.list()`](https://openemail.uk/docs/sdk/reference/roles#list). ### `openemail roles get` Read one role with its usage counts ```bash openemail roles get [flags] ``` Resolves a single role by id. There is no lookup by name, because every role's name except the owner's can be edited. `members` and `apiKeys` are counted when you call rather than stored, so they describe what a deletion would have to move right now. `permissions` is the stored list with implied permissions already expanded, in canonical order, so it can be longer than what was sent when the role was written. - Scopes: `roles:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Role id, `role_` followed by 24 hex characters. Roles have no lookup by name. **Examples** ```bash openemail roles get role_8b1f4c2e9a7d3b60e5f1a2c4 ``` Print the raw JSON ```bash openemail roles get role_8b1f4c2e9a7d3b60e5f1a2c4 --json ``` Also available in: API [`GET /roles/{id}`](https://openemail.uk/docs/api/reference/roles#get-roles-id); SDK [`roles.get()`](https://openemail.uk/docs/sdk/reference/roles#get). ### `openemail roles create` Create a custom role ```bash openemail roles create --name --permissions [flags] openemail roles create --data [flags] ``` Writes a role the workspace defines for itself. `builtin` comes back null and both usage counts are zero. Only roles like this count toward the ceiling of 24 custom roles, past which the call is 422 `role_limit_reached`. Implied permissions are expanded as the role is stored, so `templates:write` alone comes back holding `templates:read` too, and `roles:write` brings `roles:read` and `members:read`. Read the final list off the result rather than the request. A string that is not in the vocabulary is refused with 422 `invalid_parameter` rather than dropped. Be careful with `roles:write`. Authority is resolved per request, so a key holding it can edit the very role that caps it and widen itself on the next call. Keep it off keys that only need to read. - Scopes: `roles:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--name `: At most 48 characters after trimming, unique per workspace ignoring case. Blank is a 422. Required, here or in `--data`. - `--permissions ` (repeatable): What the role grants, drawn from `listPermissions`. An empty array is accepted and makes a role that can do nothing. Required, here or in `--data`. - `--description `: One sentence about who the role is for, at most 240 characters. Blank is stored as null. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail roles create --name Support --permissions threads:write,emails:send,templates:read ``` With optional flags ```bash openemail roles create --name Support --permissions threads:write,emails:send,templates:read --description 'Answers help@ and nothing else.' ``` Read the whole body from a JSON file ```bash openemail roles create --data @role.json ``` Also available in: API [`POST /roles`](https://openemail.uk/docs/api/reference/roles#post-roles); SDK [`roles.create()`](https://openemail.uk/docs/sdk/reference/roles#create). ### `openemail roles update` Rename a role or replace what it grants ```bash openemail roles update [flags] ``` Patches the name, description or permission list of a role. Every seeded role except Owner takes all three, so renaming Billing to Finance and rewriting what it grants is an ordinary update. The owner role refuses any edit with 409 `role_immutable`. `permissions` replaces the whole list and is expanded with implied permissions on the way in. There is no way to add or remove one entry, so read the role, change the array and send all of it. Leave a field out to keep it, and send `description: null` to clear the note. The change is live. Authority is resolved on every request, so narrowing a role takes effect for its members and keys on their next call without rotating anything, and widening it takes effect just as fast. - Scopes: `roles:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Role id, `role_` followed by 24 hex characters. Roles have no lookup by name. **Flags** - `--name `: New name, at most 48 characters after trimming and unique per workspace ignoring case. Blank is a 422. - `--description `: New note of at most 240 characters. Null or blank clears it. - `--permissions ` (repeatable): Complete replacement list, expanded with implied permissions before it is stored. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail roles update role_8b1f4c2e9a7d3b60e5f1a2c4 --name Finance ``` Print the raw JSON ```bash openemail roles update role_8b1f4c2e9a7d3b60e5f1a2c4 --name Finance --json ``` Also available in: API [`PATCH /roles/{id}`](https://openemail.uk/docs/api/reference/roles#patch-roles-id); SDK [`roles.update()`](https://openemail.uk/docs/sdk/reference/roles#update). ### `openemail roles delete` Delete a role and move whoever holds it ```bash openemail roles delete [flags] ``` Deletes a role. Every role except Owner can go, seeded ones included, and deleting a seeded role is permanent because seeding never runs twice. The owner role is refused with 409 `role_undeletable`. While any member, API key or unanswered invitation still points at the role, the call needs `--reassign-to` and is refused with 409 `role_in_use` without it. The server will not guess, because a key whose role vanished would fall back to no ceiling at all, which is wider than the role being removed. Members, keys and pending invitations move to the named role in one transaction. A role nobody holds deletes without it. The tombstone reports `reassigned` people and `keysReassigned` keys separately. Log the second: those programs keep running under a new ceiling and nobody is told. - Scopes: `roles:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Role id, `role_` followed by 24 hex characters. Roles have no lookup by name. **Flags** - `--reassign-to `: Id of the role that inherits the members, keys and pending invitations. Required whenever the role is held. Sent as a query parameter. **Examples** ```bash openemail roles delete role_8b1f4c2e9a7d3b60e5f1a2c4 ``` Skip the confirmation, for scripts ```bash openemail roles delete role_8b1f4c2e9a7d3b60e5f1a2c4 --yes ``` Also available in: API [`DELETE /roles/{id}`](https://openemail.uk/docs/api/reference/roles#delete-roles-id); SDK [`roles.delete()`](https://openemail.uk/docs/sdk/reference/roles#delete). ### `openemail roles list-permissions` List the permission vocabulary roles are written in ```bash openemail roles list-permissions [flags] ``` Resolves every permission as a plain array, in the canonical order a stored role's `permissions` also uses. Each entry carries the `label` to show beside a checkbox and the `group` heading it belongs under, so a permission matrix can be rendered from this rather than from a list copied into your code. `scope` is the field to branch on. Permissions and API key scopes share one alphabet, which is what lets a role cap a key, but they are not the same set. Six are console-only. `addresses:all` lets a role reach every address on every domain of the workspace, including ones added later, with no grant, `billing:read` and `billing:write` say who may see or change the plan, and `workspace:manage` who may manage the workspace. `api-keys:read` and `api-keys:write` are listed too, but API keys stay with the workspace owner whatever a role holds. No key or access token can ever hold any of the six, so they come back with `scope: false`. Filter on `scope` for a key scope picker and ignore it for a role editor. - Scopes: `roles:read`. - Needs a sign-in. **Examples** ```bash openemail roles list-permissions ``` Print the raw JSON ```bash openemail roles list-permissions --json ``` Also available in: API [`GET /roles/permissions`](https://openemail.uk/docs/api/reference/roles#get-roles-permissions); SDK [`roles.listPermissions()`](https://openemail.uk/docs/sdk/reference/roles#listPermissions).