Differences

This shows you the differences between two versions of the page.

--- zededa:zcli-how-to [2026/08/20 15:10] – mc
+++ zededa:zcli-how-to [2026/08/20 15:11] (current) – mc
@@ Line 1: / Line 1: @@
-====== ZCLI: SSH Access, Debug Knobs, and Volume Instances ======
+====== Using ZCLI ======
+A practical guide to ZEDEDA CLI (ZCLI), the command-line way to manage ZEDEDA Cloud.
+===== What ZCLI Is =====
+  * 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.
+===== Starting ZCLI =====
+<code>
+docker run -it zededa/zcli:latest
+</code>
+First run pulls the image from ZEDEDA's registry, so it takes a moment. After that you're dropped into a ''zcli>'' prompt.
+===== Logging In =====
+Two ways to authenticate: username/password, or a session token.
+==== Option 1: Username and Password ====
+  - Run ''zcli configure''
+  - Enter the server address (default is ''zedcontrol.zededa.net'')
+  - Answer **n** to "Login with token?"
+  - Enter your username and password
+  - Run ''zcli login''
+==== Option 2: Session Token ====
+  - Log in to the ZEDEDA GUI
+  - Open your user profile dropdown, top right, then **User Details**
+  - Copy the session token from the Session Information section
+  - Run ''zcli configure''
+  - Enter the server address
+  - Answer **y** to "Login with token?"
+  - Paste the token
+  - Run ''zcli login''
+===== Reading the Command Syntax =====
+  * ''<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.''
+===== Getting Help =====
+  * ''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).
+^ Key ^ Action ^
+| Space / Page Down | scroll down a page |
+| b / Page Up | scroll up a page |
+| j / Down Arrow | scroll down a line |
+| k / Up Arrow | scroll up a line |
+| / then text | search forward |
+===== Command Groups You'll Actually Use =====
+^ Command ^ What it manages ^
+| edge-node | Create, update, activate, reboot, delete edge nodes |
+| project | Resource groups that edge nodes and apps live in |
+| network | Networking objects assigned to edge node adapters |
+| network-instance | App-facing networking within an edge node |
+| edge-app | Application manifests |
+| edge-app-instance | Running app instances on edge nodes |
+| datastore | Image storage locations |
+| image | App images inside datastores |
+| volume-instance | Storage volumes |
+| events | Device events and user action logs |
+| job | Long-running tasks across nodes/instances |
+| user / role / auth-profile | Access control |
+===== Typical Flow: Bringing Up an Edge Node =====
+The GUI onboarding wizard bundles network and project setup for you. In ZCLI you do those pieces yourself, in order:
+  - Create a project: ''zcli project create <name> ...''
+  - Create a network: ''zcli network create'' (defines the subnet/DHCP mode the node's adapter will use)
+  - Create the edge node itself:
+<code>
+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
+</code>
+  - View it: ''zcli edge-node show MY_EDGE_NODE''
+  - Update it later: ''zcli edge-node update MY_EDGE_NODE --title=NEW_TITLE''
+===== Adapter-Specific Interface Config =====
+For anything beyond a single static IP, ZCLI uses a JSON template workflow instead of a giant flag list.
+  - 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
+  - Edit the json file (vi works fine in the container: **i** to insert, **Esc** to stop, **:wq** to save)
+  - Use it when creating or updating a node:
+<code>
+zcli edge-node create MY_EDGE_NODE --project=MY_PROJECT --model=Advantech-2012 \
+  --adapter-network-config=adapter-net-config-templates/adapter-net-config.json
+</code>
+  - Pull an existing node's config back out for editing: ''zcli edge-node export-adapter-config MY_EDGE_NODE''
+===== Day 2 Operations =====
+^ Task ^ Command ^
+| Reboot | ''zcli edge-node reboot -f MY_EDGE_NODE'' |
+| Graceful shutdown prep | ''zcli edge-node prepare-poweroff MY_EDGE_NODE -f'' |
+| Deactivate (stops app instances) | ''zcli edge-node deactivate MY_EDGE_NODE'' |
+| Reactivate | ''zcli edge-node activate MY_EDGE_NODE'' |
+| Update EVE-OS image | ''zcli edge-node eveimage-update MY_EDGE_NODE -f'' |
+| Remove an old EVE-OS image | ''zcli edge-node eveimage-remove MY_EDGE_NODE --image=<image>'' |
+| Pull current config to a file | ''zcli edge-node get-config MY_EDGE_NODE'' |
+| Force a config regen from cloud | ''zcli edge-node gen-config MY_EDGE_NODE'' |
+| Pull TPM PCR values | ''zcli edge-node get-pcr MY_EDGE_NODE'' |
+| Delete | ''zcli edge-node delete MY_EDGE_NODE -f'' |
+''-f'' skips the confirmation prompt. Leave it off if you want the safety check.
+===== Output Format =====
+Default output is human-readable text. Force JSON for scripting with the global flag:
+<code>
+zcli -o json edge-node show MY_EDGE_NODE
+</code>
 ===== SSH Into an Edge Node via ZCLI =====
@@ Line 128: / Line 260: @@
 | Give an app persistent or scratch disk space | ''zcli volume-instance create'' |
 | Change storage allocation thresholds device-wide | ''zcli edge-node update ... --config=storage.X:...'' |
+===== Gotchas =====
+  * 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.
 ===== Source =====
+  * 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"
-  * ZEDEDA Help Center: "ZCLI: Create and Manage Edge Nodes"