Manage Nodes - ZEDEDA Beta Docs

Use the ZEDEDA CLI (ZCLI) to manage edge nodes from the command line. This article covers zcli edge-node commands for creating and onboarding nodes, viewing and updating them, controlling their state, updating EVE-OS (Edge Virtualization Engine) images, configuring node settings, and deleting nodes, with syntax and examples for each operation. The GUI onboarding flow includes network and project configuration that the zcli edge-node command does not create for you. Create those resources first with zcli network and zcli project. See Manage Projects.

Before You Start

ZCLI is installed and authenticated against your enterprise. See Get Started.
You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
The project that the node belongs to exists, and any networks you plan to bind to node adapters exist. See Manage Projects.
For GUI-based node management, see Onboard Nodes, Manage Node Lifecycle, Node Details, and Configure Node Adapters.

Create and Onboard Nodes

Create a node

Create an edge node record in a project. The --model value must match a hardware model known to Edge Infrastructure Services. List the supported models with zcli model show. Choose one identity method for onboarding:

Onboarding key: pass --onboarding-key with the onboarding key UUID and --serial with the device serial number. The serial can be a hardware serial (printed on the device label or available from the BIOS) or a soft serial (generated during EVE-OS installation and displayed when the install finishes).
Certificate: pass --edge-node-certificate or --onboarding-certificate with the path to the certificate file.
Single-use installer: pass --gen-soft-serial to have Edge Infrastructure Services generate a soft serial for the node, then build the installer with zcli edge-node gen-single-use-eve-installer.

zcli edge-node create <name> --project=<project> --model=<model> [--title=<title>] [--description=<description>] [--tags=<key:value>...] [--local-profile-server-config=<key:value>...] ([--edge-node-certificate=<certificate>] | [--onboarding-certificate=<certificate>] | [(--onboarding-key=<key> --serial=<serial-number> [--token=<token>])]) [--network=<network>...] [--network-tag=<key:value>...] [--adapter-network-config=<json-file-path>] [--gen-soft-serial] [--edgeview-config=<json-file-path>] [--loc_url=<loc_url>] [--deployment-tag=<deployment-tag>] [--activate]

Flag	Description
`--project=<project>`	Project the node belongs to. List projects with `zcli project show`.
`--model=<model>`	Hardware model name. List models with `zcli model show`.
`--onboarding-key=<key>`	Onboarding key UUID. Use with `--serial`.
`--serial=<serial-number>`	Device hardware serial or soft serial. Use with `--onboarding-key`.
`--edge-node-certificate=<certificate>`	Path to the node certificate.
`--onboarding-certificate=<certificate>`	Path to the onboarding certificate.
`--gen-soft-serial`	Generate a soft serial for the node (single-use installer flow).
`--network=<network>`	Adapter binding as a colon-separated list: adapter name, adapter usage, network name, IP address, adapter labels (comma-separated), and optionally `allowLocalModification-true` or `allowLocalModification-false` (default false). Repeat for each adapter. List networks with `zcli network show`.
`--adapter-network-config=<json-file-path>`	Path to an adapter configuration JSON file. See Copy the adapter configuration template.
`--tags=<key:value>`	User-defined tag. Repeat for multiple tags. Use `--tags=tie-breaker:true` to mark a node as the tie-breaker in a two-node cluster.
`--local-profile-server-config=<ktype:val>`	Local profile server setting. `ktype` is `host`, `default`, or `token`. Repeat for multiple settings.
`--deployment-tag=<deployment-tag>`	Deployment tag for the node.
`--activate`	Activate the node as part of creation.

Example (onboarding key and serial):

zcli edge-node create MY_NODE --project=MY_PROJECT --model=SYS-E100-9APP --onboarding-key=MY_ONBOARDING_KEY_UUID --serial=MY_SERIAL_NUMBER

Example (static IP on the management adapter): The static IP you assign to the adapter must fall within the subnet of the network you bind it to.

zcli edge-node create MY_NODE --project=MY_PROJECT --model=SYS-E100-9APP --network=eth0:management:MY_STATIC_NET:192.168.1.100:adapterLabel1

Example (adapter configuration file):

zcli edge-node create MY_NODE --project=MY_PROJECT --model=Advantech-2012 --adapter-network-config=adapter-net-config-templates/adapter-net-config.json

Example (generate a soft serial for a single-use installer):

zcli edge-node create MY_NODE --project=MY_PROJECT --model=SYS-E100-9APP --gen-soft-serial

Generate a single-use EVE-OS installer

Generate a single-use EVE-OS installer for a node that you created with --gen-soft-serial or with the Single-Use Installer option in the GUI. The command downloads the node configuration, the bootstrap configuration, and the EVE-OS image configured for the node, and then builds an installer that contains everything the device needs to install and onboard. Use the generated installer only once and only for the specified node. The --dry-run flag runs the command in test mode without generating the installer.

zcli edge-node gen-single-use-eve-installer <name> [--dry-run]

Example:

zcli edge-node gen-single-use-eve-installer MY_NODE

Retrieve the node onboarding token

Retrieve the onboarding token record for a node.

zcli edge-node token <name>

Example:

zcli edge-node token MY_NODE

View Nodes

View a node

List all nodes, filter the list, or show one node. Use --detail for the full configuration, --summary for a short summary, --raw for raw metrics, --bootstrap for the bootstrap configuration, and --edgeview for the Edge View configuration in JSON format.

zcli edge-node show [[[<name> | --uuid=<uuid>] [--detail] [--summary] [--raw] [--bootstrap] [--edgeview]] | [[--name-pattern=<name-pattern>] [--admin-state=<admin-state>] [--page-size=<page-size>] [--project=<project>] [--state=<state>] [--tags=<key:value>]]] [--new]

Flag	Description
`--detail`	Show the full node configuration.
`--summary`	Show a summary of the node configuration.
`--raw`	Show raw metrics for the node.
`--bootstrap`	Show the bootstrap configuration for the node.
`--edgeview`	Show the Edge View configuration in JSON format. Save it to a file to reuse with `--edgeview-config`.
`--name-pattern=<name-pattern>`	List nodes whose name contains this substring.
`--project=<project>`	List nodes in this project.
`--state=<state>`	List nodes in this operational state.
`--admin-state=<admin-state>`	List nodes in this admin state.
`--tags=<key:value>`	List nodes with this tag.
`--page-size=<page-size>`	Number of records per API call. Does not change the output.

Example (all nodes):

zcli edge-node show

Example response:

Edge Node     Serial No.  State       Run State  Active Image
------------  ----------  ----------  ---------  --------------------
MY_NODE       1421        Registered  Online     12.0.6-lts-kvm-amd64
...

Example (one node):

zcli edge-node show MY_NODE

Example response:

Edge Node Name: MY_NODE
Edge Node Title: MY_NODE
Tags:
Model: Advantech-2012
Project: MY_PROJECT
State: Created
Run State: Online
Edge Node Config
Serial Number:
Configured Current Eve Image:
Configured Next Eve Image:
Device Status
Reported Serial Number:
Geo Located
Edgeview (UNSPECIFIED) Expire on: Thu Jan  1 00:00:00 1970, Dev: 0, App: 0
Created at:  Mon Mar 24 2025 10:38:13 PM  Last Config update:  Mon Mar 24 2025 10:38:13 PM

Example (filter by name):

zcli edge-node show --name-pattern=MY_

View raw metrics

Show the raw metrics that a node stores when the debug knob is enabled. See Enable the debug knob.

zcli edge-node show-raw-metrics [<name> | --uuid=<uuid>]

Example:

zcli edge-node show-raw-metrics MY_NODE

Save the node configuration to a file

Write the node configuration to a file for later use or analysis. The file is written to the current working directory of the ZCLI session (/home/zcli by default). Use --offline to write an offline configuration file, --next to show the candidate configuration, --summary for a summary, and --bootstrap to download the bootstrap configuration.

zcli edge-node get-config <name> [--offline] [--summary] [--next] [--bootstrap]

Example:

zcli edge-node get-config MY_NODE

Example response:

edge-node config written to the file MY_NODE.cfg

Get the local operator console configuration

Retrieve the local operator console (Edge Sync) configuration for a node. Configure Edge Sync before you run this command. See Configure Edge Synchronization.

zcli edge-node get-loc-config <name>

Example:

zcli edge-node get-loc-config MY_NODE

Fetch PCR values

Save the platform configuration register (PCR) values of a node to a file. Compare the retrieved values with known-good values to detect unauthorized modifications. The file is written to the current working directory of the ZCLI session (/home/zcli by default).

zcli edge-node get-pcr <name>

Example:

zcli edge-node get-pcr MY_NODE

Example response:

edge-node PCR values written to file MY_NODE.pcr

To view, set, or reset the device-level PCR attestation policy with zcli edge-node pcr-policy, see Manage a PCR Policy.

Update Nodes

Update a node

Update the title, description, tags, project, networks, configuration properties, and other settings of an existing node. Updating the adapter configuration with --network or --adapter-network-config clears the previously configured adapter settings, so specify every adapter you want to keep along with any new values.

zcli edge-node update <name> [--title=<title>] [--description=<description>] [--tags=<key:value>...] [--local-profile-server-config=<key:value>...] [--project=<project>] [--clear-onboarding-certs] [--config=<key:value>...] [--network=<network>...] [--network-tag=<key:value>...] [--adapter-network-config=<json-file-path>] [--edgeview-config=<json-file-path>] [--loc_url=<loc_url>] [--deployment-tag=<deployment-tag>]

Flag	Description
`--title=<title>`	Title of the node.
`--description=<description>`	Description of the node.
`--tags=<key:value>`	User-defined tag. Repeat for multiple tags.
`--project=<project>`	Move the node to another project.
`--config=<key:value>`	Node-specific configuration property. Repeat for multiple properties. See Set configuration properties.
`--network=<network>`	Adapter binding. Repeat for each adapter. Replaces all existing adapter settings.
`--adapter-network-config=<json-file-path>`	Adapter configuration JSON file. Replaces all existing adapter settings.
`--clear-onboarding-certs`	Clear the onboarding certificate.
`--edgeview-config=<json-file-path>`	Edge View configuration JSON file.
`--deployment-tag=<deployment-tag>`	Deployment tag for the node.

Example:

zcli edge-node update MY_NODE --title=MY_NEW_TITLE

Example (replace the adapter configuration):

zcli edge-node update MY_NODE --network=eth0:management:MY_STATIC_NET:192.168.1.100:adapterLabel1

Control Node State

Activate a node

Activate a node so that it can operate and run application instances. A newly created node becomes active by default when it comes online unless you deactivate it. If the node is already active, no action is taken.

zcli edge-node activate <name>

Example:

zcli edge-node activate MY_NODE

Deactivate a node

Deactivate a node to stop it from normal operation, for example to stop the application instances running on it and reduce resource consumption. If the node is already inactive, no action is taken.

zcli edge-node deactivate <name>

Example:

zcli edge-node deactivate MY_NODE

Reboot a node

Reboot a node remotely to apply changes or recover from issues. The command triggers a reboot event. Without -f, ZCLI prompts you to confirm. Check the node status in the GUI to confirm the reboot completed. See Node Details.

zcli edge-node reboot [-f] <name>

Example:

zcli edge-node reboot -f MY_NODE

Prepare a node for power off

Shut down all application instances on a node gracefully before you remove power. Without -f, ZCLI prompts you to confirm.

zcli edge-node prepare-poweroff <name> [-f]

Example:

zcli edge-node prepare-poweroff MY_NODE -f

Offboard a node

Offboard a node to remove it from the enterprise while preserving its device identity for re-onboarding. Without -f, ZCLI prompts you to confirm.

zcli edge-node offboard [-f] <name>

Example:

zcli edge-node offboard MY_NODE

Update EVE-OS on a Node

Update the EVE-OS image

Stage an EVE-OS image on a node. Without --activate, the image is downloaded and staged on the node without a reboot. With --activate, the node activates the image and reboots. If the node is already running the specified image, no action is taken. Use --retry to retry a failed upgrade and -f to force the upgrade. The image must be an EVE-OS image that is in the ready state. For the GUI equivalent, see Update EVE-OS on Nodes.

zcli edge-node eveimage-update <name> --image=<image> [--activate] [--retry] [-f]

Example (stage the image):

zcli edge-node eveimage-update MY_NODE --image=MY_EVE_IMAGE

Example (stage and activate the image):

zcli edge-node eveimage-update MY_NODE --image=MY_EVE_IMAGE --activate

Remove an EVE-OS image

Remove a staged EVE-OS image from a node, for example to free space or to make sure the node only keeps the current image.

zcli edge-node eveimage-remove <name> --image=<image>

Example:

zcli edge-node eveimage-remove MY_NODE --image=MY_EVE_IMAGE

Configure Node Settings

Set configuration properties

Set node-specific configuration properties with the --config option of zcli edge-node update. The key and value are separated by a colon, and the value can itself contain colons. Repeat --config to set several properties in one command. Node-level properties take precedence over the same properties set at the project level. For the list of properties, see Set Log Levels. Example (enable SSH access with a public key):

zcli edge-node update MY_NODE --config=debug.enable.ssh:"MY_PUBLIC_KEY"

Example (disable SSH access by clearing the key):

zcli edge-node update MY_NODE --config=debug.enable.ssh:""

Example (set several properties):

zcli edge-node update MY_NODE --config=configInterval.Timer:60 --config=log.count.filenames:/pillar/types/zedroutertypes.go:1079

Copy the adapter configuration template

Copy the adapter configuration template files to a directory so that you can edit a fresh template and use it to configure adapters on a new node, or to replace the adapter configuration of an existing node. A relative <path> is resolved from the current working directory of the ZCLI session (/home/zcli by default). If you omit <path>, the files are copied to an adapter-net-config-templates directory in the current working directory. The template includes the following files:

adapter-net-config.json, the base configuration template that you edit.
adapter-net-config.jsonc, a commented copy with examples and explanations.
adapter-net-config.md, documentation of each field and its constraints.

Edit adapter-net-config.json according to your hardware model, then pass the file with --adapter-network-config when you create or update a node. Use this file-based approach when you bound an adapter to a network created with --dhcp=static-adapter-specific and need to supply the adapter-specific IP details.

zcli edge-node copy-adapter-config-template [<path>]

Example:

zcli edge-node copy-adapter-config-template

Example response:

Copied adapter-net-config.json to /home/zcli/adapter-net-config-templates
Copied adapter-net-config.jsonc to /home/zcli/adapter-net-config-templates
Copied adapter-net-config.md to /home/zcli/adapter-net-config-templates
Adapter config template files copied to directory: /home/zcli/adapter-net-config-templates

Export the adapter configuration

Export the current adapter configuration of a node to a JSON file named <name>_adapter_config.json in the current working directory of the ZCLI session. Edit the file, then pass it with --adapter-network-config to zcli edge-node update to apply the changes.

zcli edge-node export-adapter-config [<name> | --uuid=<uuid>]

Example:

zcli edge-node export-adapter-config MY_NODE

Example response:

Adapter config exported to file: MY_NODE_adapter_config.json

Example (apply the edited file):

zcli edge-node update MY_NODE --adapter-network-config=MY_NODE_adapter_config.json

Enable the debug knob

Enable the debug knob so that the node stores raw metrics. Use --expiry to set when the debug knob expires. View the stored metrics with zcli edge-node show-raw-metrics. For more about logs, see Set Log Levels.

zcli edge-node enable-debug-knob <name> [--expiry=<expiry>]

Example:

zcli edge-node enable-debug-knob MY_NODE

Disable the debug knob

Disable the debug knob so that the node stops storing raw metrics.

zcli edge-node disable-debug-knob <name>

Example:

zcli edge-node disable-debug-knob MY_NODE

Delete Nodes

Delete a node

Delete a node record that you no longer need. Without -f, ZCLI prompts you to confirm. Unlike the console, which can delete a node’s dependents for you, the edge-node delete command deletes only the node record. Edge Infrastructure Services refuses the delete while any of the following is true:

The node belongs to an Edge Node Cluster. The error is device is attached to the edge node cluster with id: <uuid>. Replace the node in the cluster or delete the cluster first. The edge-node-cluster command group does not remove individual nodes; the only command that does is the deprecated edge-kubernetes-cluster remove-nodes. See Remove Nodes from a Cluster.
Application instances are still deployed on the node. The error is <N> app instances still attached to this device. Delete them with zcli app-instance delete first.
Virtual networks other than the default are still configured on the node. The error is <N> non-default network instances still attached to this device. Delete them with zcli network-instance delete first.

zcli edge-node delete <name> [-f]

Example:

zcli edge-node delete MY_NODE -f

Other Operations

Trigger configuration generation

Check the latest configuration that Edge Infrastructure Services holds for the node and generate an updated configuration for it.

zcli edge-node gen-config <name>

Example:

zcli edge-node gen-config MY_NODE

Start an Edge View session

Start an Edge View session on a node. The project policy must allow Edge View first. See Configure Edge View With CLI.

zcli edge-node start-edgeview <name>

Example:

zcli edge-node start-edgeview MY_NODE

Stop an Edge View session

End the active Edge View session on a node.

zcli edge-node stop-edgeview <name>

Example:

zcli edge-node stop-edgeview MY_NODE

Get the Edge View client script

Retrieve the Edge View client script for a node.

zcli edge-node get-edgeview-script <name>

Example:

zcli edge-node get-edgeview-script MY_NODE

Next Steps

Onboard Nodes

Onboard a node using the Edge Intelligence Platform Console.

Manage Node Lifecycle

Activate, deactivate, reboot, off-board, and delete nodes in the GUI.

Configure Node Adapters

GUI-based adapter and network port configuration.

Overview

All ZCLI command procedures, organized by resource type.

​Before You Start

​Create and Onboard Nodes

​Create a node

​Generate a single-use EVE-OS installer

​Retrieve the node onboarding token

​View Nodes

​View a node

​View raw metrics

​Save the node configuration to a file

​Get the local operator console configuration

​Fetch PCR values

​Update Nodes

​Update a node

​Control Node State

​Activate a node

​Deactivate a node

​Reboot a node

​Prepare a node for power off

​Offboard a node

​Update EVE-OS on a Node

​Update the EVE-OS image

​Remove an EVE-OS image

​Configure Node Settings

​Set configuration properties

​Copy the adapter configuration template

​Export the adapter configuration

​Enable the debug knob

​Disable the debug knob

​Delete Nodes

​Delete a node

​Other Operations

​Trigger configuration generation

​Start an Edge View session

​Stop an Edge View session

​Get the Edge View client script

​Next Steps

Onboard Nodes

Manage Node Lifecycle

Configure Node Adapters

Overview

Before You Start

Create and Onboard Nodes

Create a node

Generate a single-use EVE-OS installer

Retrieve the node onboarding token

View Nodes

View a node

View raw metrics

Save the node configuration to a file

Get the local operator console configuration

Fetch PCR values

Update Nodes

Update a node

Control Node State

Activate a node

Deactivate a node

Reboot a node

Prepare a node for power off

Offboard a node

Update EVE-OS on a Node

Update the EVE-OS image

Remove an EVE-OS image

Configure Node Settings

Set configuration properties

Copy the adapter configuration template

Export the adapter configuration

Enable the debug knob

Disable the debug knob

Delete Nodes

Delete a node

Other Operations

Trigger configuration generation

Start an Edge View session

Stop an Edge View session

Get the Edge View client script

Next Steps