Skip to content

roles command group

roles manages the ADMIN-scope role lifecycle in {{ product_name }}. Use it to search the administrator role catalog (TEMPLATE and CUSTOM roles), rename or re-describe CUSTOM roles, delete CUSTOM roles, and clone any role into a new editable CUSTOM role.

Remote command: host profile and login required

The roles commands are remote gRPC calls. Before running any of them, create a host profile with profile hosts create and authenticate with profile authn login. Select a one-shot profile with the global -p/--profile option (default default-admin), placed before the command path.

TEMPLATE vs CUSTOM roles

TEMPLATE roles are built-in and immutable: they cannot be edited or deleted. Only CUSTOM roles can be edited or deleted. To customize a TEMPLATE role, clone it into a new CUSTOM role first with roles clone.

Commands in this group

Command Purpose
roles search Search the ADMIN-scope roles (TEMPLATE and CUSTOM)
roles edit Edit a CUSTOM ADMIN role's name and/or description
roles delete Delete a CUSTOM ADMIN role
roles clone Clone an ADMIN role into a new editable CUSTOM role

Group help

bin/admin.sh roles --help

Search the ADMIN-scope roles. With no query term the full ADMIN role set is returned. Search, mode, and pagination behavior come from the shared query mixins.

Syntax

bin/admin.sh roles search [options]

Required options

This command has no command-specific required options.

Optional options

Show optional options
Option Default Description
-q, --query none Query string; omit to return the full ADMIN role set
-m, --query-mode QUERY_MODE_ILIKE Query mode: QUERY_MODE_WEB, QUERY_MODE_PLAIN, or QUERY_MODE_ILIKE
-n, --query-page-number 1 Start page (first page is page number 1)
-s, --query-page-size 50 Page size (minimum 1, maximum 250)
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh roles search -q "operator" -m QUERY_MODE_ILIKE -n 1 -s 50 -f json

roles edit

Edit a CUSTOM ADMIN role's name and/or description, addressed by its UUID. TEMPLATE roles are not editable and are rejected server-side.

Syntax

bin/admin.sh roles edit [options]

Required options

Option Description
-u, --uuid UUID of the CUSTOM role to edit

Conditionally required options

Condition Required options
The role must change At least one of -N/--name or -d/--description

Optional options

Show optional options
Option Description
-N, --name New role name
-d, --description New role description
-f, --out-format Output format: JSON or YAML (default YAML)

Validation rules

  • At least one of -N/--name or -d/--description must be supplied; otherwise the command fails with an invalid-input error.
  • TEMPLATE roles cannot be edited; the server rejects edits to non-CUSTOM roles.

Example

bin/admin.sh roles edit \
  -u 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -N "Senior CA Operator" \
  -d "Operators with elevated CA permissions" \
  -f json

roles delete

Delete a CUSTOM ADMIN role by UUID. TEMPLATE roles are not deletable, and the backend refuses deletion when the calling administrator is a member of the role (self-protection).

Syntax

bin/admin.sh roles delete [options]

Required options

Option Description
-u, --uuid UUID of the CUSTOM role to delete

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Validation rules

  • TEMPLATE roles cannot be deleted; only CUSTOM roles are deletable.
  • Deletion is refused when the calling administrator is a member of the target role.

Example

bin/admin.sh roles delete -u 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f -f json

roles clone

Clone any ADMIN role (TEMPLATE or CUSTOM) into a new editable CUSTOM role with a new name and a copy of the source role's grants.

Syntax

bin/admin.sh roles clone [options]

Required options

Option Description
-s, --source-uuid UUID of the ADMIN role to clone
-N, --name Name for the new CUSTOM role

Optional options

Show optional options
Option Description
-d, --description Description for the new role; defaults to the source role's description
-f, --out-format Output format: JSON or YAML (default YAML)

Example

bin/admin.sh roles clone \
  -s 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -N "Custom CA Operator" \
  -d "Cloned from the CA Operator template" \
  -f json

Standard CLI options are documented in Global options.

Typical workflow

  1. Find the role to work with using roles search.
  2. Clone a TEMPLATE role into an editable CUSTOM role with roles clone.
  3. Adjust the CUSTOM role's name or description with roles edit.
  4. Remove a CUSTOM role you no longer need with roles delete.

FAQ

Can I edit or delete a TEMPLATE role?

No. TEMPLATE roles are immutable. Clone the TEMPLATE into a CUSTOM role with roles clone, then edit or delete the CUSTOM role.

Why does roles edit fail when I pass only -u?

roles edit requires at least one of -N/--name or -d/--description so the command has a change to apply. Supply one or both alongside -u/--uuid.

Why can't I delete a role I belong to?

The backend refuses deletion when the calling administrator is a member of the target role. This self-protection prevents an administrator from removing their own access.

Do I need to log in before running roles commands?

Yes. The roles commands are remote gRPC calls. Create a host profile with profile hosts create and authenticate with profile authn login first.