Skip to main content
Use the ZEDEDA CLI (ZCLI) to manage application images from the command line. This article covers zcli image commands, with syntax and examples for each operation. An application image is the virtual machine disk, container, Docker Compose TAR archive, or other file that an edge application uses. You reference images from an edge application, and EVE-OS (Edge Virtualization Engine) on the edge node downloads them from a datastore when it deploys an application instance. Adding an image always takes two steps:
  1. Create an image record in Edge Infrastructure Services with zcli image create. The record holds the image name, format, architecture, type, and the datastores where the file is stored.
  2. Associate the image file with the record. There are two ways to do this.
    • Upload the file from your computer with zcli image upload. ZCLI copies the file into a ZEDEDA-managed datastore.
    • Uplink a file that is already stored in a datastore with zcli image uplink. You give Edge Infrastructure Services the file’s location, SHA-256 checksum, and size, and the file is not copied.
When the file is associated, the image status changes to READY and you can use the image in an edge application. See Manage Edge Apps.

​
Before You Start

  • ZCLI is installed and authenticated against your enterprise. See Get Started.
  • You have the SysManager role in your enterprise. See Manage Roles.
  • The datastore for the image already exists. See Manage Datastores.
  • To upload a file, the datastore must be a ZEDEDA-managed datastore (type ZEDEDAS3 or ZEDEDABLOB). To use a datastore of any other type, store the file there yourself and uplink it.

​
Image Types

The kind of image you create depends on which of the following flags you pass to zcli image create. create requires exactly one of --arch, --patch-artifact-image, or --compose-tar-image. With --arch, you can also set --type: If you pass --type together with --compose-tar-image or --patch-artifact-image, ZCLI ignores --type.

​
Create an Image Record

​
Create an image record

The syntax shows the datastore flags as optional, but create requires one of them. Without --datastore-name or --datastores, ZCLI prints Please provide datastore details and does not create the record.
ZCLI does not check --image-format or the project names in --project-scope before it sends the request. If a project name in --project-scope does not exist, ZCLI does not report an error. Check the names with zcli project show before you create the image.
To create an AMD64 application image record in one datastore:
To create an ARM64 image record in two datastores, with a title, available to two projects:
To create a Docker Compose TAR image record:
To create a patch artifact image record:

​
Add the Image File

​
Upload a file from your computer

Upload the image file into the image record’s datastore. The image record must already exist.
ZCLI uploads the file in 2 MiB chunks and shows a progress bar. When the transfer finishes, ZCLI prints Uploading in progress. Check upload status with "zcli image show <name>". Run that command until the status is READY. Example:
  1. Upload the file:
  2. Check the status until it is READY:
Upload works only when every datastore in the image record is a ZEDEDA-managed datastore. For any other datastore type, ZCLI prints Image upload to datastore of type <type> not supported. and does not upload. Uplink the file instead.
ZCLI cannot resume an interrupted upload. Run the upload again to send the whole file from the beginning. If the image status is still UPLOADING or UPLINKING, ZCLI prints Image upload/uplink in progress already and does not start a new upload.
Uplinking associates the image record with a file that is already stored in a datastore. Use uplink for any datastore type, and for large files that you have already copied to your own storage.
The syntax shows --image-sha and --image-size as optional, but they are required for every format except container. Without them, ZCLI prints Error Input --image-sha is mandatory field. or Error Input --image-size is mandatory field. and does not uplink the image. --image-size must be a whole number of bytes. Any other value, such as 220M, stops ZCLI with a Python error.
To get the checksum and size of a file, run the following commands in the directory where the file is stored. On macOS, get the checksum:
On macOS, get the size in bytes:
On Linux, get the checksum:
On Linux, get the size in bytes:
To uplink a file that is already in a datastore:
To uplink a container image in a container registry datastore:
[TBD: confirm the --image-url format for a container image in a container registry datastore, for example whether it includes the tag.]

​
Add a Docker Compose TAR image

A Docker Compose TAR image holds the contents of a Docker Compose application directory.
  1. Put all of the application’s files (for example, compose.yaml, .env files, and supporting scripts) in a single directory, for example my-compose-app.
  2. From the parent directory, create a gzipped TAR archive of the directory’s contents.
  3. Create the image record.
  4. Upload the archive.
  5. Check that the image status is READY.
To deploy the archive, create a Docker Compose edge application that references the image. See Docker Compose.

​
View Images

​
View a single image

Show an image by name or UUID. Add --detail to include the description, project scope, all datastore names, upload or uplink errors, the relative URL, and version history.
To view an image:
To view the full details of an image:
The output includes the image status. The common values are CREATED (the record exists but has no file), UPLOADING, UPLINKING, READY, and FAILED. If the status is FAILED, run zcli image show <name> --detail and read the Upload / Uplink Error Status line. --latest shows the default EVE-OS image for an architecture. See EVE-OS Images.

​
List images

Run zcli image show without a name to list images. The list shows each image’s name, title, type, format, size, and status. Use the following flags to filter the list.
--datastore-name clears the --arch, --type, and --status filters. If you combine them, ZCLI lists every image in the datastore, regardless of architecture, type, or status. --name-pattern, --patch-artifact-image, and --compose-tar-image still apply.
To list all images:
To list ARM64 images whose name contains ubuntu:
To list Docker Compose TAR images:
To list images whose upload or uplink failed:
To show only a summary of images:

​
View project scope

Show the projects that can use one or more images. When you name several images, the output shows the projects that they have in common.
Example:

​
Update an Image Record

Update an image record’s title, architecture, project scope, origin type, datastores, or file details.
You cannot change an image’s name, format, or type. To change them, delete the image and create it again. If you pass no options, ZCLI prints Nothing to update and makes no change.
--project-scope and --datastores replace the current values. They are not added to them. To add a project, pass every project that should keep access. Run zcli image show <name> --detail first to see the current values.
To change the title of an image:
To replace the list of projects that can use an image:

​
Delete an Image

​
Delete an image record

Delete an image by name. ZCLI asks Delete image <name>? [Y/N] unless you pass -f. If you answer no, ZCLI prints Image <name> not deleted.
To delete an image and confirm when prompted:
To delete an image without a confirmation prompt:
Deleting an image record does not delete the file from the datastore. Remove the file from the datastore separately if you no longer need it.

​
Delete images by keyword

--match deletes every image whose name contains the keyword, in every active enterprise that your account can see. ZCLI does not ask for confirmation, and -f has no effect. A short keyword, such as v1, can match many images. Before you use --match, run zcli image show --name-pattern=<keyword> to see which images in your enterprise match.
ZCLI prints the name of every image that it checks and <name> deleted for each image that it deletes.

​
EVE-OS Images

EVE-OS images use the same zcli image commands as application images, with --type=Eve. The following pages cover the EVE-OS procedures in full:

​
View the default EVE-OS image

​
Set the default EVE-OS image

Example:

​
Onboard an EVE-OS image to other enterprises

onboard uploads an EVE-OS image to your enterprise if it is not there already, and then uplinks it to other enterprises that your account can see.
In the current ZCLI version, onboard stops after the first target enterprise that it processes. Enterprises that are not active are skipped. To add the image to several enterprises, run onboard once for each enterprise with --enterprise=<enterprise>, and then check the image in each enterprise with zcli image show.

​
Next Steps

Manage Edge Apps

Create edge applications that reference your images.

Manage Datastores

Create and manage the datastores that hold image files.

Manage Application Instances

Deploy edge applications to edge nodes as application instances.

Overview

All ZCLI command procedures, organized by resource type.