Skip to content

grants command group

The grants command group of the {{ product_name }} alpine-admin-cli manages the AUTHZ grants that bind an ADMIN role to permissions and their CRUDX operation masks. A grant joins a role (identified by its --role-uuid) to a permission name and a CRUDX mask describing the allowed create, read, update, delete, and execute operations.

grants search is read-only and works for both TEMPLATE and CUSTOM roles. grants add, grants edit, and grants delete modify grants and are accepted only for CUSTOM roles; built-in TEMPLATE roles are immutable.

Remote command: profile and login required

Every command in this group is a remote gRPC call. Before running them you must create a host profile with profile hosts create and authenticate with profile authn login. Use the global -p/--profile option (default default-admin), placed before the command path, to select the host profile for a one-shot invocation. See Global options.

Commands in this group

Command Purpose
grants search List the grants of an ADMIN role
grants add Add a grant to a CUSTOM ADMIN role
grants edit Change a grant's CRUDX mask on a CUSTOM ADMIN role
grants delete Revoke a grant from a CUSTOM ADMIN role

Typical workflow

  1. List existing grants for a role with grants search.
  2. Add a new permission grant with grants add, supplying the CRUDX mask.
  3. Adjust an existing grant's mask with grants edit.
  4. Revoke a grant you no longer need with grants delete.

Group help

bin/admin.sh grants --help

Lists the AUTHZ grants of an ADMIN role. This command is read-only and works for both TEMPLATE and CUSTOM roles.

Syntax

bin/admin.sh grants search [options]

Required options

Option Description
-u, --role-uuid UUID of the ADMIN role whose grants are listed

Optional options

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

Example

bin/admin.sh grants search \
  --role-uuid 1f3b9c7e-2a4d-4f6b-8c0e-9d1a2b3c4d5e \
  -f json

grants add

Adds an AUTHZ grant (a permission plus a CRUDX operation mask) to a CUSTOM ADMIN role. TEMPLATE roles are not editable. The CRUDX mask is parsed and validated by the server.

Syntax

bin/admin.sh grants add [options]

Required options

Option Description
-u, --role-uuid UUID of the CUSTOM ADMIN role
-p, --permission AUTHZ permission name to grant
-o, --ops CRUDX mask in positional c r u d x form, with - to disable a position (for example crudx, -r---, cru--)

Optional options

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

Validation rules

  • --ops is a five-position CRUDX mask: position 1 = create, 2 = read, 3 = update, 4 = delete, 5 = execute. Use the operation letter to enable a position and - to disable it (for example -r--- grants read only).
  • The permission name passed to --permission must be a known AUTHZ permission; the server rejects unknown permissions.
  • The role identified by --role-uuid must be a CUSTOM role. Grants on TEMPLATE roles cannot be added.

Example

bin/admin.sh grants add \
  --role-uuid 1f3b9c7e-2a4d-4f6b-8c0e-9d1a2b3c4d5e \
  --permission certificate.issue \
  --ops crudx \
  -f json

grants edit

Changes the CRUDX mask of an existing grant on a CUSTOM ADMIN role. The grant is identified by the role plus the permission name; the new mask replaces the previous one. TEMPLATE roles are not editable.

Syntax

bin/admin.sh grants edit [options]

Required options

Option Description
-u, --role-uuid UUID of the CUSTOM ADMIN role
-p, --permission AUTHZ permission name of the grant to change
-o, --ops New CRUDX mask in positional c r u d x form, with - to disable a position (for example crudx, -r---)

Optional options

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

Validation rules

  • --ops is a five-position CRUDX mask: position 1 = create, 2 = read, 3 = update, 4 = delete, 5 = execute. Use the operation letter to enable a position and - to disable it.
  • A grant for the given --permission must already exist on the role; the edit replaces its mask rather than creating a new grant.
  • The role identified by --role-uuid must be a CUSTOM role. Grants on TEMPLATE roles cannot be edited.

Example

bin/admin.sh grants edit \
  --role-uuid 1f3b9c7e-2a4d-4f6b-8c0e-9d1a2b3c4d5e \
  --permission certificate.issue \
  --ops -r--- \
  -f yaml

grants delete

Revokes a grant from a CUSTOM ADMIN role. The grant is identified by the role plus the permission name. TEMPLATE roles' grants are not deletable.

Syntax

bin/admin.sh grants delete [options]

Required options

Option Description
-u, --role-uuid UUID of the CUSTOM ADMIN role
-p, --permission AUTHZ permission name of the grant to revoke

Optional options

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

Validation rules

  • The role identified by --role-uuid must be a CUSTOM role. Grants on TEMPLATE roles cannot be revoked.
  • A grant for the given --permission must exist on the role.

Example

bin/admin.sh grants delete \
  --role-uuid 1f3b9c7e-2a4d-4f6b-8c0e-9d1a2b3c4d5e \
  --permission certificate.issue \
  -f json

Standard CLI options are documented in Global options.

FAQ

What is the CRUDX mask used by --ops?

The CRUDX mask is a five-position string covering create, read, update, delete, and execute. Use the operation letter to enable a position and - to disable it: crudx enables all five, while -r--- grants read only.

Can I add, edit, or delete grants on a TEMPLATE role?

No. Built-in TEMPLATE roles are immutable. Only CUSTOM roles accept grants add, grants edit, and grants delete. You can still list a TEMPLATE role's grants with grants search.

How is a grant identified for edit and delete?

A grant is identified by the combination of --role-uuid and the AUTHZ --permission name. There is no separate grant identifier; the role plus permission pair locates the grant.

Do grants commands require a login?

Yes. All grants commands are remote gRPC calls, so they require a host profile created with profile hosts create and an authenticated session from profile authn login.