Using ZCLI

A practical guide to ZEDEDA CLI (ZCLI), the command-line way to manage ZEDEDA Cloud.

• ZCLI is one of three ways to talk to ZEDEDA Cloud. The other two are the GUI and the API.
• It ships as a Docker container, not a native binary.
• You need Docker Desktop running before you start it.

docker run -it zededa/zcli:latest

First run pulls the image from ZEDEDA's registry, so it takes a moment. After that you're dropped into a zcli> prompt.

Two ways to authenticate: username/password, or a session token.

1. Run zcli configure
2. Enter the server address (default is zedcontrol.zededa.net)
3. Answer n to “Login with token?”
4. Enter your username and password
5. Run zcli login

1. Log in to the ZEDEDA GUI
2. Open your user profile dropdown, top right, then User Details
3. Copy the session token from the Session Information section
4. Run zcli configure
5. Enter the server address
6. Answer y to “Login with token?”
7. Paste the token
8. Run zcli login

• <name> is a value you supply
• [–title=<title>] is optional
• [–clear-text=<true|false>] means pick one of the listed choices

If you leave out something required, ZCLI tells you plainly, e.g. Missing required option –dstype.

• zcli by itself lists every command group.
• zcli <command> –help shows syntax for that command.
• man zcli-<command> opens the full manual page (press q to exit).

The GUI onboarding wizard bundles network and project setup for you. In ZCLI you do those pieces yourself, in order:

1. Create a project: zcli project create <name> …
2. Create a network: zcli network create (defines the subnet/DHCP mode the node's adapter will use)
3. Create the edge node itself:

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

1. View it: zcli edge-node show MY_EDGE_NODE
2. Update it later: zcli edge-node update MY_EDGE_NODE –title=NEW_TITLE

For anything beyond a single static IP, ZCLI uses a JSON template workflow instead of a giant flag list.

1. Copy the templates: zcli edge-node copy-adapter-config-template
   • Drops adapter-net-config.json (the one you edit) plus .jsonc and .md reference copies, to /root/zcli/adapter-net-config-templates by default
2. Edit the json file (vi works fine in the container: i to insert, Esc to stop, :wq to save)
3. Use it when creating or updating a node:

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

1. Pull an existing node's config back out for editing: zcli edge-node export-adapter-config MY_EDGE_NODE

-f skips the confirmation prompt. Leave it off if you want the safety check.

Default output is human-readable text. Force JSON for scripting with the global flag:

zcli -o json edge-node show MY_EDGE_NODE

SSH access to EVE-OS is off by default. You turn it on by pushing your public key to the node's debug.enable.ssh property through ZCLI. This was originally meant for EVE developer debugging, not production use, keep that in mind before leaving it on.

cat ~/.ssh/id_rsa.pub

If that's empty, generate one first:

ssh-keygen -b 2048 -t rsa

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

Or pull the key straight from the file instead of pasting it:

zcli edge-node update EDGE_NODE --config="debug.enable.ssh:$(cat ~/.ssh/id_rsa.pub)"

Note: this survives until you clear it, but if you re-onboard or re-image the device, the key gets wiped and you'll need to push it again.

Pull it from zcli edge-node show EDGE_NODE –detail, or from the GUI's device status page.

ssh -i ~/.ssh/id_rsa root@<edge-node-ip>

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

An empty string clears every authorized key. Verify it actually cleared before you walk away from the box.

ZEDEDA recommends Edge View over raw SSH for production environments. It adds policy control at the node/project/enterprise level, session time limits, and audit logs, things plain SSH doesn't give you. Worth using instead of SSH unless you specifically need a raw shell.

Same –config pattern used for SSH above:

zcli edge-node update EDGE_NODE --config="KEY:VALUE"

Changes sync on the node's next config check (default every 60 seconds, tunable via timer.config.interval).

A separate, unrelated command turns on raw metrics collection rather than a –config property:

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

That one is specifically for storing raw metrics on the device, don't confuse it with the debug.enable.* config properties above.

This is a different thing from the knobs above. A volume instance is persistent or scratch storage you attach to an app running on a specific edge node, not a debug switch.

zcli volume-instance create MY-VOL-INST --volume-type=CONTENT_TREE --project=MY-PROJECT \
  --edge-node=MY-EDGE-NODE --size=100 --access-mode=READWRITE

For an edge node cluster instead of a single node, swap –edge-node for –edge-node-cluster.

zcli volume-instance show --edge-node=MY-EDGE-NODE

zcli volume-instance update MY-VOL-INST --title=NEW-TITLE
zcli volume-instance delete MY-VOL-INST -f

Volume instances are created the same way regardless. What decides persistence is the Purge setting on the edge app that consumes the volume: leave Purge unchecked and the volume survives app updates and restarts. Check it, and the volume gets wiped on purge/update.

One catch: a persistent volume instance belongs to the specific edge node it was created on. Same behavior on multiple nodes means a separate volume instance per node, it doesn't automatically replicate.

• Most successful commands print nothing. Silence means it worked, only failures produce output.
• TLS verification is on by default. –no-verify / -k turns it off, only use this if you know why you need to.
• The GUI onboarding wizard does more behind the scenes (network + project wiring) than zcli edge-node create alone. If a node created via ZCLI looks half-configured, check whether you also need the zcli network and zcli project steps first.
• debug.enable.ssh and volume instances solve different problems. SSH knobs get you a shell on the node itself. Volume instances give an app storage. Don't reach for one when you mean the other.

• ZEDEDA Help Center: “ZEDEDA CLI Overview”
• ZEDEDA Help Center: “ZCLI: Create and Manage Edge Nodes”
• ZEDEDA Help Center: “How to Enable and Disable SSH for Edge Nodes”
• ZEDEDA Help Center: “Update Edge Node Configuration Properties”
• ZEDEDA Help Center: “ZCLI: Create and Manage Volume Instances”
• ZEDEDA Help Center: “Add Persistent Volume Instances”