Skip to main content
Use the ZEDEDA CLI (ZCLI) to manage roles from the command line. This article covers zcli role commands, with syntax and examples for each operation. A role defines what its users can do: which objects they can create, read, update, or delete, in which enterprises, and in which projects. You assign a role to a user with zcli user. See Manage Users. This page is the command reference. For an explanation of role types and the permissions of the built-in System roles, see Manage Roles.

​
Before You Start

  • ZCLI is installed and authenticated against your enterprise. See Get Started.
  • You have the SysAdmin role in your enterprise. See Manage Roles.
  • Any project that you plan to name in a project scope already exists. ZCLI looks up each project by name and rejects the command if a project is not found.

​
Access Right Format

You define a role’s permissions with --access-right. Each --access-right value is one scope: a comma-separated list of object:action pairs, plus optional enterprise-scope and project-scope entries that limit where those permissions apply. Enclose the whole value in quotes.

​
Objects

​
Actions

Combine the letters c (create), r (read), u (update), and d (delete) to grant several permissions. Write the letters in c, r, u, d order. For example, ru, cru, and crud are valid, but ur and rc are not. Letters are not case-sensitive. Any other combination of the four letters is also valid if the letters appear in c, r, u, d order, for example rd or cud. There is no value for “no access”. To give a scope no access to an object, leave that object out of the scope.
ZCLI does not validate action values before it uses them. A value that is out of order or contains other letters, such as ur, rw, or none, stops the command with an Unexpected error executing command 'role' message that names KeyError and the invalid value. No role is created or changed. Correct the value and run the command again.

​
Scopes

Keep the following rules in mind:
  • Separate multiple project names with spaces, not commas, inside a single project-scope entry. Because ZCLI splits the list on spaces, a project whose name contains a space cannot be used in a project scope.
  • Use only local or global for enterprise-scope. ZCLI passes any other value to Edge Infrastructure Services unchanged, without checking it.
  • To apply different permissions to different projects, repeat --access-right. Each --access-right value creates a separate scope with its own objects, actions, and filters.
If ZCLI cannot parse an entry, it prints one of the following messages and does not send the request:

​
Access right examples

Full access to nodes, edge applications, and application instances in one project, with read access to users:
Read-only access across two projects:
Two scopes in one role: full access in one project and read-only access in another:

​
Create a Role

​
Create a custom role

Create a custom role with one or more scopes. --access-right is required.
ZCLI creates the role as a user-defined (custom) role. Example:

​
View Roles

​
View a single role

Show one role by name or UUID, or show the role of the user who is logged in with --self. Add --detail to include the description, version, and creation and modification history.
Example:
The output lists the role’s ID, name, title, type, and state, followed by one row per scope. In each scope row:
  • E-Scope shows local or global.
  • P-Scope shows the project names, or All if the scope applies to all projects.
  • The access columns show the granted actions in uppercase, for example CRUD or RU. An object that is not part of the scope is empty or shows NONE.
  • The EntrpriseLevelObjectAccess column, which corresponds to enterprise-integration-items, shows the full API value, for example PermissionAccessCreateReadUpdateDelete, instead of letters.

​
List roles

Run zcli role show without a name to list all roles, including the built-in System roles. Use the following flags to filter the list. To list all roles:
To list roles whose name contains Operator:
To list roles with a project scope that includes two projects:

​
Update a Role

​
Update a custom role

Update a role’s title, description, or access rights.
--access-right on update replaces all of the role’s existing scopes. ZCLI does not merge the new values with the current ones. As a result:
  • Any scope that you do not pass again is removed from the role.
  • Any object that you leave out of a scope has no access in that scope.
  • If you omit enterprise-scope or project-scope, that scope resets to your own enterprise or to all projects.
Before you update access rights, run zcli role show <name> --detail to see the current scopes, and then pass the complete set of scopes that the role should have.
If you pass only --title or --description, ZCLI keeps the role’s existing scopes unchanged. If you pass no options, ZCLI prints Nothing to update. and makes no change. Example: change only the title:
Example: replace the role’s access rights with full access in MY_PROJECT and read-only access in MY_PROJECT_B:
You can update only custom roles. The built-in System roles are read-only. See Manage Roles.

​
Delete a Role

​
Delete a custom role

Delete a role by name. ZCLI asks Delete role <name>? [Y/N] unless you pass -f. If you answer no, ZCLI prints Role <name> not deleted.
Example:
You can delete only custom roles that are not assigned to any user. Before you delete a role, assign a different role to its users. See Manage Users.

​
Next Steps

Manage Users

Create users and assign roles to them in one or more enterprises.

Manage Roles

Role types and the permissions of the built-in System roles.

Get Started

Install ZCLI, configure access to Edge Infrastructure Services, and sign in.

Overview

All ZCLI command procedures, organized by resource type.