Skip to main content
Use the ZEDEDA CLI (ZCLI) to manage application instances from the command line. This article covers zcli edge-app-instance commands for deploying an instance of an edge app to an edge node or node cluster, viewing instances, controlling their lifecycle, updating their configuration, attaching patch envelopes, working with snapshots, and deleting instances, with syntax and examples for each operation. An application instance is a deployed copy of an edge app running on a specific edge node. The edge app definition (image, resources, and interfaces) is managed separately with zcli edge-app. The same zcli edge-app-instance commands apply to virtual machine, container, and Docker Compose application instances. For background on compose instances, see Docker Compose Overview.

​
Before You Start

​
Deploy Application Instances

​
Create an application instance

Create an application instance record from an edge app and deploy it to a single edge node (--edge-node) or to an edge node cluster (--edge-node-cluster). When you deploy to a cluster, you can optionally pin the instance to one node in the cluster with --enable-app-pinning=true together with --designated-node-id. This is the ZCLI equivalent of the Deploy flow in the console. Each --network-instance and --adapter value maps an interface name defined in the edge app to a resource on the node. The interface name must match an interface in the edge app definition, or ZCLI rejects the command with Interface <name> not found in edge app template.
In the current version of ZCLI, --adapter-tag does not work reliably on create or update. If you pass --adapter-tag without --adapter, ZCLI stops with a Python error (UnboundLocalError) and does not create or update the instance. If you pass it together with --adapter, ZCLI looks up the interface position of the first adapter tag from the preceding --adapter value, so the tag can be assigned to the wrong interface position. Until this is fixed, bind adapters by name with --adapter.

​
Interface binding formats

A --network-instance value starts with the interface name and the virtual network name, separated by a colon. You can append more colon-separated values after the virtual network name. ZCLI identifies each value by its content. ZCLI ignores appended values that match none of these patterns, without an error. Because the value is split at each colon, you cannot set an IPv6 address this way. Example (bind eth0 to a virtual network with a static IP address, a MAC address, and access VLAN 100):
A --network-tag value takes the form <interface>:<tag-key>:<tag-value>, or <interface>:<tag-key>:<tag-value>:<vlan-id> to also set an access VLAN ID. ZCLI ignores a --network-tag value with more than three colons, without an error. Example (bind eth0 by tag and set access VLAN 100):

​
Examples

Example (deploy to a single node with the edge app defaults):
Example (bind interface eth0 to a virtual network and interface usb0 to a physical adapter):
Example (bind an interface to a virtual network by tag instead of by name):
Example (deploy to a node cluster and pin the instance to one node):

​
View Application Instances

​
View application instances

List all application instances in your enterprise, filter the list by project, edge app, edge node, cluster, state, name substring, or tag, or show one instance by name or UUID. Add --detail to a single-instance query to print the full configuration. Add --summary to a list query to print only the count summaries. Use --page-size to reduce the number of records returned per API call if a large list times out; it does not change the output.
Example (all application instances):
Example response:
Example (filter by project, state, and name substring):
Example (all instances on one edge node):
Example (one application instance):
Example response:
Example (full configuration of one application instance):
For the meaning of the admin and run states in the output, see Application Instance Status and Health.

​
Control Application Instances

The following commands change the running state of an application instance on its edge node without changing its configuration. Each one corresponds to an action in the console Actions menu on the instance detail page.

​
Start an application instance

Start an application instance that is halted or that was created but not activated. Existing volumes and network connections are preserved. This is the ZCLI equivalent of the console Start action.
Example:

​
Stop an application instance

Stop an application instance on its edge node. Stopping halts the entire instance, not just its containers, and the application is unavailable until you start it again. Persistent volumes are preserved. This is the ZCLI equivalent of the console Stop action.
Example:

​
Restart an application instance

Stop and restart an application instance. Expect a brief outage while the instance restarts. This is the ZCLI equivalent of the console Restart action.
Example:

​
Refresh or purge an application instance

Refresh an application instance to update it to the latest version of its edge app. A refresh restarts the instance but keeps its data. This is the ZCLI equivalent of the console Update action. Add --purge to clear all local application data and redeploy from the latest edge app version. A purge is destructive: the instance returns to its initial state and all local data is lost. This is the ZCLI equivalent of the console Purge & Update action. If snapshots are enabled for the instance, consider creating a snapshot first so you have a rollback point. See Snapshots.
Example (refresh, data is kept):
Example (refresh and purge, data is lost):

​
Update Application Instances

​
Update an application instance

Update the title, description, tags, start delay, local profile server override, or interface bindings of an existing application instance. ZCLI retrieves the current record, applies the values you pass, and writes the modified record back. Flags you omit keep their current values. This is the ZCLI equivalent of the console Configure (gear) action.
Example (change the description):
Example (set a staggered start delay and add a tag):

​
Manage Patch Envelopes

A patch envelope delivers runtime bundle artifacts to a running application instance without redeploying it. The same patch envelope can be attached to several instances in one command. All instances named in one command must belong to the project you pass with --project. Patch envelopes are not available for Docker Compose application instances. For how to create patch envelopes, see Update Applications with Runtime Bundles.

​
Attach a patch envelope

Attach a patch envelope to one or more application instances. Repeat --app-instance for each instance. This is the ZCLI equivalent of the console Attach Patch Envelope action.
Example:

​
Detach a patch envelope

Detach the currently attached patch envelope from one or more application instances. Files previously delivered by the envelope are no longer available to the application. This is the ZCLI equivalent of the console Detach Patch Envelope action.
Example:

​
Snapshots

A snapshot captures the current state of an application instance, including its configuration and attached volumes, so you can roll back to that state. Snapshots are useful for instances on edge nodes that are air-gapped or offline for long periods. Snapshots must be enabled for the instance, and only one snapshot is retained per instance; creating a new snapshot replaces the existing one. Snapshots are not available for Docker Compose application instances. For an overview, see Application Snapshot Overview.

​
Create a snapshot

Create a snapshot of an application instance. This is the ZCLI equivalent of the console Create Snapshot action. Without -f, ZCLI first checks that the hosting edge node supports immediate snapshots and, if it does not, stops with the message The related device doesn't support immediate snapshots. With -f, ZCLI skips this check and submits the request anyway.
Example:

​
View snapshots

List the snapshots of an application instance, or show one snapshot by name. Use the list output to find the snapshot name for the activate and delete commands.
Example (all snapshots of one application instance):
Example response:
Example (one snapshot):

​
Activate a snapshot

Roll the application instance back to the state captured in a snapshot. This is the ZCLI equivalent of the console Rollback action on the Storage tab of the instance detail page.
Example:

​
Delete a snapshot

Delete a snapshot of an application instance. This is the ZCLI equivalent of the console Delete action for a snapshot on the Storage tab.
Example:

​
Delete Application Instances

​
Delete an application instance

Delete an application instance from its edge node. This action is irreversible. Without -f, ZCLI prompts you to confirm the deletion. This is the ZCLI equivalent of the console Delete action.
Example:

​
Next Steps

Applications Overview

How edge apps, images, and application instances fit together.

Deploy an Application Instance

Deploy an instance using the Edge Infrastructure Services console.

Manage an Application Instance

GUI-based lifecycle actions, snapshots, and patch envelopes.

Overview

All ZCLI command procedures, organized by resource type.