Skip to main content

​
Introduction

ZCLI (ZEDEDA CLI) is a Docker-based command-line interface for interacting with Edge Infrastructure Services. It provides the same management capabilities as the console GUI and supports scripting and automation for routine operations. ZCLI is one of three user agents available for Edge Infrastructure Services. The others are the console GUI and the ZEDEDA API.

​
Prerequisites

  • Docker Desktop installed and running.
  • A ZEDEDA user account.

​
Start ZCLI

ZCLI runs as a Docker container. The first time you start it, Docker pulls the required images from the ZEDEDA registry. This might take a few moments.

​
Authenticate

​
Authenticate with your ZEDEDA credentials

  1. Run the configure command to start the authentication prompt.
  1. Specify the server address. The default is zedcontrol.zededa.net.
  2. Answer n when prompted with Login with token?(y/n) [n]:.
  3. Enter your Username and Password.
  4. Specify the Output format for command responses, either text or json. The default is text.
  5. Log in.

​
Authenticate with a session token

  1. Log in to the ZEDEDA console.
  2. Select the Profile avatar in the header and select Profile Settings.
  3. In the Session Information section, copy your session token.
  4. Run the configure command.
  1. Specify the server address.
  2. Answer y when prompted with Login with token?(y/n) [n]:.
  3. Paste the session token and press Enter.
  4. Specify the Output format for command responses, either text or json. The default is text.
  5. Log in.
When you run zcli configure again, ZCLI shows each current value in brackets. Press Enter to keep a value.

​
Configure without prompts

To configure ZCLI in a script, pass the values as options. ZCLI prompts only for values that you do not provide.
To use a token instead of a username and password:

​
Authenticate with environment variables

If ZCLI has not been configured, it can log in with credentials from environment variables instead. Set all three of the following variables when you start the container:
  • ZSERVER: the server address.
  • ZEDUSER: your username.
  • ZEDPASSWORD: your password.
With these variables set, ZCLI logs in automatically each time you run a command, so you do not need to run zcli configure or zcli login. ZCLI uses the environment variables only when no configuration exists. After you run zcli configure, ZCLI uses the saved configuration and ignores the variables.

​
Log Out

To end your session, run:
ZCLI ends the session and removes the session token from its configuration. Your server, username, and output format remain configured, so you can run zcli login to start a new session.

​
Work With Local Files

Some commands read files from your computer, such as hardware model manifests, adapter network configurations, and PCR template files. ZCLI runs inside a container, so you must make those files available inside the container first. The container’s working directory is /home/zcli.

​
Mount a local directory

Start ZCLI with the -v option to mount a local directory into the container. The following example mounts the current directory at /home/zcli/files:
Inside the container, refer to the files by that path, for example files/manifest.json. Files that ZCLI writes to the mounted directory, such as exported manifests, also appear on your computer.

​
Copy a file into a running container

If ZCLI is already running, copy the file from another terminal on your computer.
  1. Find the container ID.
  1. Copy the file into the container.

​
Available Commands

To see all available commands, run zcli without arguments. For a description of every command group and a link to its procedures, see Command Index.

​
Command Help

To see options and required parameters for a specific command, add --help to the command. For example, to see the options for the datastore command:
ZCLI prints the usage for every subcommand. The following is an abbreviated response:
Reading the syntax:
  • Items within angle brackets are your own specific variables, such as <name>.
  • Items within square brackets are optional, such as [--title=<title>].
  • Items that contain a pipe are choices, such as between true or false in [--clear-text=<true|false>].
If you type the syntax incorrectly, such as by omitting a required option, ZCLI returns an error message. For example, this command omits the required --dstype option:
ZCLI responds:

​
Man Pages

To view the manual page for a specific command, prefix the command name with zcli-. For example, to view the manual page for edge-node:
Navigate man pages using:

​
Next Steps

Overview

All ZCLI command procedures, organized by resource type.

ZEDEDA API Overview

Introduction to available ZEDEDA API services and versioning.

Edge Infrastructure Services Overview

Introduction to Edge Infrastructure Services capabilities and service areas.

Onboard Nodes

Enroll edge nodes in Edge Infrastructure Services.