> ## Documentation Index > Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL. > Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other. > Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking. > Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify. # Manage Roles > Use ZCLI commands to create, view, update, and delete custom roles and their access rights from the command line. 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](https://zededa.mintlify.site/zcli-reference/users.md). This page is the command reference. For an explanation of role types and the permissions of the built-in System roles, see [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md). ## Before You Start * ZCLI is installed and authenticated against your enterprise. See [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md). * You have the SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md). * 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. ```text theme={"dark"} --access-right=":,:,...,enterprise-scope:,project-scope: ..." ``` ### Objects | Object | What it controls | Column in `role show` output | | - | - | - | | `user` | User management. | `User Access` | | `edge-node` | Edge node management. | `EdgeNodeAccess` | | `edge-app` | Edge application management. | `EdgeAppAccess` | | `app-instance` | Application instance management. | `AppInstanceAccess` | | `enterprise` | Enterprise management. | `EntrpriseAccess` | | `enterprise-integration-items` | Enterprise integration items (third-party integrations). | `EntrpriseLevelObjectAccess` | | `app` | Legacy object kept for older scripts. It sets the same action on both `edge-app` and `app-instance`. Use `edge-app` and `app-instance` in new commands. | Not shown separately | ### 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. | Value | Permissions | | - | - | | `r` | Read. | | `ru` | Read and update. | | `cru` | Create, read, and update. | | `crud` | Create, read, update, and delete. | 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. > [!WARNING] > > 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 | Entry | Values | Default if omitted | | - | - | - | | `enterprise-scope` | `local` limits the scope to your own enterprise. `global` applies it to all enterprises. | `local` | | `project-scope` | One or more project names, separated by spaces. Each project must already exist. | All projects | 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: | Message | Cause | | - | - | | `Incorrect access-right scope/right format: "" should be object:access (e.g. user:crud, edge-node:cr)` | An entry has no colon. | | `Invalid access-right scope/right type: ` | The object or scope name is not one of the names in the preceding tables. | | `Invalid project-scope: "" does not exist` | A project in `project-scope` was not found in your enterprise. | ### Access right examples Full access to nodes, edge applications, and application instances in one project, with read access to users: ```text theme={"dark"} --access-right="user:r,edge-node:crud,edge-app:crud,app-instance:crud,enterprise-scope:local,project-scope:MY_PROJECT" ``` Read-only access across two projects: ```text theme={"dark"} --access-right="user:r,edge-node:r,edge-app:r,app-instance:r,enterprise-scope:local,project-scope:MY_PROJECT_A MY_PROJECT_B" ``` Two scopes in one role: full access in one project and read-only access in another: ```text theme={"dark"} --access-right="edge-node:crud,edge-app:crud,app-instance:crud,project-scope:MY_PROJECT_A" --access-right="edge-node:r,edge-app:r,app-instance:r,project-scope:MY_PROJECT_B" ``` ## Create a Role ### Create a custom role Create a custom role with one or more scopes. `--access-right` is required. ```text theme={"dark"} zcli role create --access-right=... [--title=] [--description=<description>] ``` | Flag | Description | | - | - | | `--access-right` | Required. One scope of permissions. Repeat for multiple scopes. See [Access Right Format](#access-right-format). | | `--title` | Display title of the role. If you omit it, ZCLI uses the role name. | | `--description` | Description of the role. | ZCLI creates the role as a user-defined (custom) role. Example: ```text theme={"dark"} zcli role create MY_ROLE --title="Project Operator" --description="Full access to nodes and apps in MY_PROJECT" --access-right="user:r,edge-node:crud,edge-app:crud,app-instance:crud,enterprise-scope:local,project-scope:MY_PROJECT" ``` ## 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. ```text theme={"dark"} zcli role show [[[<name> | --self | --uuid=<uuid>] [--detail]] | [[--name-pattern=<name-pattern>] [--summary] [--page-size=<page-size>] [--project=<project>]]] ``` Example: ```text theme={"dark"} zcli role show MY_ROLE --detail ``` 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. | Flag | Description | | - | - | | `--name-pattern` | Show only roles whose name contains this substring. | | `--project` | Show only roles with a project scope that includes these projects. Separate multiple project names with spaces and enclose them in quotes. If a project does not exist, ZCLI prints `Invalid project: "<project>" does not exist`. | | `--summary` | Show a count of roles by state instead of the list. | | `--page-size` | Number of records each API call returns. This changes only how many calls ZCLI makes, not the output. | To list all roles: ```text theme={"dark"} zcli role show ``` To list roles whose name contains `Operator`: ```text theme={"dark"} zcli role show --name-pattern=Operator ``` To list roles with a project scope that includes two projects: ```text theme={"dark"} zcli role show --project="MY_PROJECT_A MY_PROJECT_B" ``` ## Update a Role ### Update a custom role Update a role's title, description, or access rights. ```text theme={"dark"} zcli role update <name> [--access-right=<object-access>...] [--title=<title>] [--description=<description>] ``` > [!WARNING] > > `--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: ```text theme={"dark"} zcli role update MY_ROLE --title="Project Operator (Production)" ``` Example: replace the role's access rights with full access in `MY_PROJECT` and read-only access in `MY_PROJECT_B`: ```text theme={"dark"} zcli role update MY_ROLE --access-right="user:r,edge-node:crud,edge-app:crud,app-instance:crud,enterprise-scope:local,project-scope:MY_PROJECT" --access-right="edge-node:r,edge-app:r,app-instance:r,enterprise-scope:local,project-scope:MY_PROJECT_B" ``` You can update only custom roles. The built-in System roles are read-only. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md). ## 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.` ```text theme={"dark"} zcli role delete <name> [-f] ``` Example: ```text theme={"dark"} zcli role delete MY_ROLE -f ``` 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](https://zededa.mintlify.site/zcli-reference/users.md). ## Next Steps > [card] [Manage Users](https://zededa.mintlify.site/zcli-reference/users.md) > > Create users and assign roles to them in one or more enterprises. > [card] [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md) > > Role types and the permissions of the built-in System roles. > [card] [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md) > > Install ZCLI, configure access to Edge Infrastructure Services, and sign in. > [card] [Overview](https://zededa.mintlify.site/zcli-reference/overview.md) > > All ZCLI command procedures, organized by resource type.