Skip to main content
Use the ZEDEDA CLI (ZCLI) to manage users from the command line. This article covers zcli user commands, with syntax and examples for each operation. A user is an account that signs in to Edge Infrastructure Services. Each user has one or more allowed enterprises, and a role in each of those enterprises that controls what the user can do there. For the console procedures, see Manage Users. To create or change the roles that you assign to users, see Manage Roles.

​
Before You Start

  • ZCLI is installed and authenticated against your enterprise. See Get Started.
  • You have a role that allows you to manage users in your enterprise. [TBD: confirm the minimum role required to create, update, and delete users with ZCLI.]
  • To create local users (users who sign in with a ZEDEDA password), your enterprise uses local authentication. If an OAuth authentication profile is active, users are provisioned through your Identity Provider instead. See Manage Authentication Profiles.
The option list that zcli user --help prints contains several flag names that ZCLI does not accept. Use the flag names in the syntax lines on this page, which match the commands that ZCLI accepts.

​
Create a User

Create a user record. Choose how the user signs in: with a password (--password), through your OAuth Identity Provider (--oauth), or with no credential set yet.
--public-key-path has no effect on create. ZCLI does not read the key file, and it creates the user with no credential. The same happens if you omit --password, --public-key-path, and --oauth. To give the user a credential afterwards, use Reset the credential for another user.
Always pass --lastname when you create a user. If you omit it, ZCLI trims the text “None” from the generated full name, and this can also remove the letters N, o, n, or e from the start of the first name. For example, a user created with --firstname=Nora and no last name gets the full name ra instead of Nora.
Example of a local user with access to two enterprises who receives notifications by email and SMS:
Example of an OAuth user:

​
Password rules

When you create a user with --password, ZCLI checks that the password meets the following rules before it sends the request. If a rule fails, ZCLI prints the reason and does not create the user.
  • At least 8 characters.
  • At least one number.
  • At least one capital letter.
  • At least one of the following special characters: @ _ ! # $ % ^ & * ( ) < > ? / | } { ~ :.
Your enterprise’s password policy can set stricter rules, which Edge Infrastructure Services applies when it receives the request. See Password Policy Parameters. ZCLI checks these rules only on create. It does not check them on change-credential or reset-credential, so a password that breaks your password policy is rejected by Edge Infrastructure Services instead.

​
Enterprise access and roles

Each --allowed-enterprise value pairs an enterprise with a role, in the format <enterprise>:<role>. For example, --allowed-enterprise=MY_ENTERPRISE:SysManager.
  • The enterprise must be the enterprise you are signed in to or one of its child enterprises. If it is not, ZCLI prints Invalid enterprise: <name>. Valid enterprises are: followed by the list of enterprises that you can use.
  • The value must contain exactly one colon. A value without a role, such as --allowed-enterprise=MY_ENTERPRISE, makes ZCLI print Invalid input: MY_ENTERPRISE.
  • ZCLI does not check that the role exists. Check the role name with zcli role show before you run the command. See Manage Roles.
When an --allowed-enterprise value is invalid, ZCLI prints the error but does not stop the command. On create, ZCLI still sends the create request, without any allowed enterprises. On update, ZCLI still sends your other changes and leaves the user’s enterprises unchanged. Check the output for Invalid input or Invalid enterprise, then run zcli user show <name> to confirm the result.

​
View Users

​
View a single user

Show one user by name or UUID, or show your own user with --self. Add --detail for the full record, including phone, locale, time zone, notification preference, last sign-in and sign-out times, and revision history.
To show a user by name:
To show the full record for a user:
To show your own user:
The output lists each allowed enterprise and the user’s role in it. The Role field shows the user’s role in the enterprise that you are signed in to. A role that your own role does not allow you to read is left blank.

​
List users

Run zcli user show without a name to list all users in your enterprise. Filter the list with the following flags. Example:
Example response:
The Role column shows each user’s role in the enterprise that you are signed in to. The column is blank for a user who has no role in that enterprise.

​
View active users

Show the users who performed an action in a time range, with the time of each user’s most recent action.
ZCLI reads the times in the local time zone of the system that runs ZCLI, and it shows the results in that time zone. Inside the ZCLI Docker container, the local time zone is usually UTC. Quote the values because they contain a space. Example:

​
Update a User

Update another user by name, or update your own user with --self. Pass only the values that you want to change. ZCLI keeps the other values.
The flags have the same meaning as on create, with the following additions:
--allowed-enterprise replaces the whole list of the user’s enterprises. It does not add to it. Any enterprise that you leave out is removed from the user. To add an enterprise or change one role, first run zcli user show <name> to see the current list, then pass every enterprise that the user should keep.
  • zcli user update --self ignores --allowed-enterprise. You cannot change your own enterprise access or role with ZCLI.
  • ZCLI rebuilds the full name from the first name and the last word of the current full name. If the current full name is a single word with no space, user update fails with a Python error. Pass both --firstname and --lastname to avoid this.
Example of changing a user’s last name:
Example of giving a user access to two enterprises with a different role in each. The command replaces any enterprises that the user had before.
Example of updating your own phone number and notification preference:

​
Manage Credentials

​
Change your own credential

Change the password or public key of the user that you are signed in as.
Example:

​
Reset the credential for another user

Set a new password or public key for another user, for example when the user has forgotten the password or was created without a credential.
Unlike change-credential, reset-credential does not read a file for --new-public-key. ZCLI sends the value exactly as you type it, so a file path is sent as the key. [TBD: confirm with engineering whether --new-public-key on reset-credential expects the key text, and how to pass it.]
Example:

​
Activate or Deactivate a User

Deactivate a user to block access temporarily without deleting the user. Activate the user to restore access. To deactivate a user:
To activate a user:
The following example deactivates a user:
The following example activates the same user again:

​
Delete a User

Delete a user permanently. ZCLI asks for confirmation unless you pass -f.
Example:

​
Next Steps

Manage Roles

Create and update the roles that you assign with --allowed-enterprise.

Manage Authentication Profiles

Set the password policy for local users or connect an Identity Provider.

Manage Users

Manage users in the Edge Infrastructure Services console.

Overview

All ZCLI command procedures, organized by resource type.