> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Manage Nodes

> Use ZCLI commands to create, onboard, view, update, control, and delete edge nodes, and to manage EVE-OS images and node settings from the command line.

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](https://zededa.mintlify.site/zcli-reference/projects.md).

## Before You Start

* ZCLI is installed and authenticated against your enterprise. See [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md).
* You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).
* The project that the node belongs to exists, and any networks you plan to bind to node adapters exist. See [Manage Projects](https://zededa.mintlify.site/zcli-reference/projects.md).
* For GUI-based node management, see [Onboard Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/onboard-nodes.md), [Manage Node Lifecycle](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/manage-node-lifecycle.md), [Node Details](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/node-details.md), and [Configure Node Adapters](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/configure-node-adapters.md).

## 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`.

```text theme={"dark"}
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](#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):

```text theme={"dark"}
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.

```text theme={"dark"}
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):

```text theme={"dark"}
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):

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node gen-single-use-eve-installer <name> [--dry-run]
```

Example:

```text theme={"dark"}
zcli edge-node gen-single-use-eve-installer MY_NODE
```

### Retrieve the node onboarding token

Retrieve the onboarding token record for a node.

```text theme={"dark"}
zcli edge-node token <name>
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
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):

```text theme={"dark"}
zcli edge-node show
```

Example response:

```text theme={"dark"}
Edge Node     Serial No.  State       Run State  Active Image
------------  ----------  ----------  ---------  --------------------
MY_NODE       1421        Registered  Online     12.0.6-lts-kvm-amd64
...
```

Example (one node):

```text theme={"dark"}
zcli edge-node show MY_NODE
```

Example response:

```text theme={"dark"}
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):

```text theme={"dark"}
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](#enable-the-debug-knob).

```text theme={"dark"}
zcli edge-node show-raw-metrics [<name> | --uuid=<uuid>]
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node get-config <name> [--offline] [--summary] [--next] [--bootstrap]
```

Example:

```text theme={"dark"}
zcli edge-node get-config MY_NODE
```

Example response:

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/configure-edge-synchronization.md).

```text theme={"dark"}
zcli edge-node get-loc-config <name>
```

Example:

```text theme={"dark"}
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).

```text theme={"dark"}
zcli edge-node get-pcr <name>
```

Example:

```text theme={"dark"}
zcli edge-node get-pcr MY_NODE
```

Example response:

```text theme={"dark"}
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](https://zededa.mintlify.site/zcli-reference/pcr-policy.md).

## 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.

```text theme={"dark"}
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](#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:

```text theme={"dark"}
zcli edge-node update MY_NODE --title=MY_NEW_TITLE
```

Example (replace the adapter configuration):

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node activate <name>
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node deactivate <name>
```

Example:

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/node-details.md).

```text theme={"dark"}
zcli edge-node reboot [-f] <name>
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node prepare-poweroff <name> [-f]
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node offboard [-f] <name>
```

Example:

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/update-eve-os-on-nodes.md).

```text theme={"dark"}
zcli edge-node eveimage-update <name> --image=<image> [--activate] [--retry] [-f]
```

Example (stage the image):

```text theme={"dark"}
zcli edge-node eveimage-update MY_NODE --image=MY_EVE_IMAGE
```

Example (stage and activate the image):

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node eveimage-remove <name> --image=<image>
```

Example:

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/troubleshooting/set-log-levels.md).

Example (enable SSH access with a public key):

```text theme={"dark"}
zcli edge-node update MY_NODE --config=debug.enable.ssh:"MY_PUBLIC_KEY"
```

Example (disable SSH access by clearing the key):

```text theme={"dark"}
zcli edge-node update MY_NODE --config=debug.enable.ssh:""
```

Example (set several properties):

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node copy-adapter-config-template [<path>]
```

Example:

```text theme={"dark"}
zcli edge-node copy-adapter-config-template
```

Example response:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node export-adapter-config [<name> | --uuid=<uuid>]
```

Example:

```text theme={"dark"}
zcli edge-node export-adapter-config MY_NODE
```

Example response:

```text theme={"dark"}
Adapter config exported to file: MY_NODE_adapter_config.json
```

Example (apply the edited file):

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/troubleshooting/set-log-levels.md).

```text theme={"dark"}
zcli edge-node enable-debug-knob <name> [--expiry=<expiry>]
```

Example:

```text theme={"dark"}
zcli edge-node enable-debug-knob MY_NODE
```

### Disable the debug knob

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

```text theme={"dark"}
zcli edge-node disable-debug-knob <name>
```

Example:

```text theme={"dark"}
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](https://zededa.mintlify.site/zcli-reference/kubernetes-clusters.md#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.

```text theme={"dark"}
zcli edge-node delete <name> [-f]
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli edge-node gen-config <name>
```

Example:

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/edge-view/configure-edge-view-with-cli.md).

```text theme={"dark"}
zcli edge-node start-edgeview <name>
```

Example:

```text theme={"dark"}
zcli edge-node start-edgeview MY_NODE
```

### Stop an Edge View session

End the active Edge View session on a node.

```text theme={"dark"}
zcli edge-node stop-edgeview <name>
```

Example:

```text theme={"dark"}
zcli edge-node stop-edgeview MY_NODE
```

### Get the Edge View client script

Retrieve the Edge View client script for a node.

```text theme={"dark"}
zcli edge-node get-edgeview-script <name>
```

Example:

```text theme={"dark"}
zcli edge-node get-edgeview-script MY_NODE
```

## Next Steps

> [card] [Onboard Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/onboard-nodes.md)
>
> Onboard a node using the Edge Intelligence Platform Console.

> [card] [Manage Node Lifecycle](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/manage-node-lifecycle.md)
>
> Activate, deactivate, reboot, off-board, and delete nodes in the GUI.

> [card] [Configure Node Adapters](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/configure-node-adapters.md)
>
> GUI-based adapter and network port configuration.

> [card] [Overview](https://zededa.mintlify.site/zcli-reference/overview.md)
>
> All ZCLI command procedures, organized by resource type.