CLI v1.10.0

Using the CLI

Control the Edera Protect daemon.

protect [OPTIONS] <COMMAND>

Subcommands:

• zone Manage the zones on Edera Protect.
• workload Manage the workloads on Edera Protect.
• image Manage the images on Edera Protect.
• network Manage the network on Edera Protect.
• device Manage the devices on Edera Protect.
• host Manage the host of Edera Protect.
• completion Output shell completion code for the specified shell.

zone

Manage the zones on Edera Protect.

protect zone <COMMAND>

Subcommands:

• attach Attach to the zone console.
• list List zone information.
• resolve Resolve a zone name to matching zone ids.
• launch Launch a new zone.
• destroy Destroy a zone.
• suspend Suspend a running zone.
• resume Resume a suspended zone.
• fork Fork a running zone into a new memory-shared child zone.
• exec Execute a command inside the zone.
• forget Forget destroyed zones (clear their tombstones).
• logs View the logs of a zone.
• metrics Read metrics from the zone.
• top Dashboard for running zones.
• watch Watch for zone changes.
• update-resources Update the available resources to a zone.
• configure-network Configure the network of an external network backend zone.
• kernel-events Manage kernel events from zones.

attach

Attach to the zone console.

protect zone attach <ZONE>

Arguments:

• <ZONE> Zone to attach to, either the name or the uuid.

list

List zone information.

protect zone list [OPTIONS] [ZONE]

Arguments:

• <ZONE> Limit to a single zone, either the name or the uuid.

Options:

• -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].
• -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘ready’, ‘destroying’, ‘destroyed’, ‘failed’, ‘suspending’, ‘suspended’, ‘resuming’ and ‘forking’, with or without the ‘zone_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=ZONE_STATE_FAILED).

resolve

Resolve a zone name to matching zone ids.

protect zone resolve [OPTIONS] <NAME>

Arguments:

• <NAME> The zone name to resolve.

Options:

• -f, --first If there are multiple matching zones, only print the first zone id.

launch

Launch a new zone.

protect zone launch [OPTIONS]

Options:

• --pull-overwrite-cache Overwrite image cache on pull.
• --pull-update Update image on pull.
• -n, --name <NAME> Name of the zone.
• --min-cpus <MIN_CPUS> Minimum vCPUs available for the zone [default value: 4].
• -C, --max-cpus <MAX_CPUS> Maximum vCPUs available for the zone [default value: 4].
• -c, --target-cpus <TARGET_CPUS> Target vCPUs for the zone to use [default value: 1].
• --min-memory <MIN_MEMORY> Minimum memory available to the zone, in megabytes [default value: 0].
• -M, --max-memory <MAX_MEMORY> Maximum memory available to the zone, in megabytes [default value: 1024].
• -m, --target-memory <TARGET_MEMORY> Target memory for the zone to use, in megabytes [default value: 1024].
• --create-scratch-disk <CREATE_SCRATCH_DISK> Create a scratch disk of size, in megabytes.
• --attach-scratch-disk <ATTACH_SCRATCH_DISK> Attach a host disk as a scratch disk.
• -D, --device <DEVICE> Devices to request for the zone.
• -a, --attach Attach to the zone after zone starts, implies –wait.
• -W, --wait Wait for the zone to be ready, implied by –attach.
• -k, --kernel <KERNEL> OCI kernel image for zone to use.
• -I, --initrd <INITRD> OCI initrd image for zone to use.
• -w, --working-directory <WORKING_DIRECTORY> Working directory.
• --kernel-verbose Enable verbose logging on the kernel.
• --kernel-cmdline <KERNEL_CMDLINE> Additional kernel cmdline options.
• --kernel-module <KERNEL_MODULE> Additional kernel modules to load.
• --kernel-module-parameter <KERNEL_MODULE_PARAMETER> Additional kernel module parameters to add.
• --kernel-cmdline-append <KERNEL_CMDLINE_APPEND> Additional kernel cmdline options (raw).
• --assume-network-reservation <ASSUME_NETWORK_RESERVATION> Assume an already allocated network reservation.
• --retain-network-reservation Retain network reservation after zone destruction.
• -R, --resource-adjustment-policy <RESOURCE_ADJUSTMENT_POLICY> Resource adjustment policy [possible values: static, dynamic].
• -V, --virt-backend <VIRT_BACKEND> Virtualization backend [possible values: auto, pv, pvh].
• -N, --network-backend <NETWORK_BACKEND> Network backend [possible values: default, none, external, passthrough].
• --numa-nodes <NUMA_NODES> Requested vNUMA node count; 0 (default) lets the daemon pick based on vCPU count and host topology [default value: 0].
• --numa-strategy <NUMA_STRATEGY> Strategy for selecting additional NUMA nodes beyond the seed [default value: compact] [possible values: compact, scatter].
• -A, --addon <ADDON> Addons for the zone.
• --sysctl <SYSCTL> sysctl parameters to set on the zone.
• --control-api-access <CONTROL_API_ACCESS> Enables access to the Control API from inside a zone [possible values: deny, allow].

destroy

Destroy a zone.

protect zone destroy [OPTIONS] [ZONE_IDENTIFIER]

Arguments:

• <ZONE_IDENTIFIER> Zone to destroy, either the name or the uuid. Optional when --selector is specified.

Options:

• -W, --wait Wait for the destruction of the zone to complete.
• -A, --all Destroy all zones matching the input.
• -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘ready’, ‘destroying’, ‘destroyed’, ‘failed’, ‘suspending’, ‘suspended’, ‘resuming’ and ‘forking’, with or without the ‘zone_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=ZONE_STATE_FAILED).

suspend

Suspend a running zone.

protect zone suspend <ZONE>

Arguments:

• <ZONE> Zone to suspend, either the name or the uuid.

resume

Resume a suspended zone.

protect zone resume <ZONE>

Arguments:

• <ZONE> Zone to resume, either the name or the uuid.

fork

Fork a running zone into a new memory-shared child zone.

protect zone fork [OPTIONS] <ZONE>

Arguments:

• <ZONE> Zone to fork, either the name or the uuid.

Options:

• -n, --name <NAME> Name for the forked child zone.

exec

Execute a command inside the zone.

protect zone exec [OPTIONS] <ZONE> [COMMAND]...

Arguments:

• <ZONE> Zone to exec inside, either the name or the uuid.
• <COMMAND> Command to run inside the zone.

Options:

• -e, --env <ENV> Environment variables.
• -w, --working-directory <WORKING_DIRECTORY> Working directory.
• -t, --tty Allocate tty.
• --privileged Execute command with elevated privileges.

forget

Clears the tombstone record for destroyed zones. Tombstones are the in-memory record retained after a zone is destroyed so post-mortem tooling (protect zone logs, debug reports) can still inspect them. They expire automatically after the daemon’s linger window; this command evicts them sooner – most importantly so a new zone can reuse a destroyed zone’s name without ambiguity. Forgetting a tombstone is low-risk: the live zone is already gone, so the only consequence of being wrong is losing post-mortem visibility into the destroyed zone. That’s why a bare protect zone forget (no arguments) forgets every tombstone – it’s the most common operation (“tidy up”) and has no failure mode worth gating behind a flag.

protect zone forget [OPTIONS] [ZONE]

Arguments:

• <ZONE> Optional zone name or uuid. If omitted, every tombstone is forgotten. If a name matches multiple tombstones, --all is required to disambiguate.

Options:

• -A, --all When <ZONE> is a name matching multiple tombstones, forget all of them rather than refusing.

logs

View the logs of a zone.

protect zone logs [OPTIONS] <ZONE>

Arguments:

• <ZONE> Zone to show logs for, either the name or the uuid.

Options:

• -f, --follow Follow output from the zone.

metrics

Read metrics from the zone.

protect zone metrics [OPTIONS] <ZONE>

Arguments:

• <ZONE> Zone to read metrics for, either the name or the uuid.

Options:

• -o, --output <OUTPUT> Output format [default value: tree] [possible values: tree, json, json-pretty, yaml, key-value].

top

Dashboard for running zones.

protect zone top

watch

Watch for zone changes.

protect zone watch [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, json, key-value].

update-resources

Update the available resources to a zone.

protect zone update-resources [OPTIONS] <ZONE>

Arguments:

• <ZONE> Zone to update resources of, either the name or the uuid.

Options:

• --min-cpus <MIN_CPUS> Minimum vCPUs available to the zone (0 means previous value) [default value: 0].
• -C, --max-cpus <MAX_CPUS> Maximum vCPUs available to the zone (0 means previous value) [default value: 0].
• -c, --target-cpus <TARGET_CPUS> Target vCPUs for the zone to use (0 means previous value) [default value: 0].
• --min-memory <MIN_MEMORY> Minimum memory available to the zone, in megabytes (0 means previous value) [default value: 0].
• -M, --max-memory <MAX_MEMORY> Maximum memory available to the zone, in megabytes (0 means previous value) [default value: 0].
• -m, --target-memory <TARGET_MEMORY> Target memory for the zone to use, in megabytes (0 means previous value) [default value: 0].
• -p, --adjustment-policy <ADJUSTMENT_POLICY> Adjustment policy [possible values: static, dynamic].

configure-network

Configure the network of an external network backend zone.

protect zone configure-network [OPTIONS] <ZONE>

Arguments:

• <ZONE> Zone to update resources of, either the name or the uuid.

Options:

• --zone-interface <ZONE_INTERFACE> Zone Network Interface.
• --zone-ipv4 <ZONE_IPV4> Zone IPv4 Network.
• --zone-ipv6 <ZONE_IPV6> Zone IPv6 Network.
• --gateway-ipv4 <GATEWAY_IPV4> Zone Gateway IPv4 Network.
• --gateway-ipv6 <GATEWAY_IPV6> Zone Gateway IPv6 Network.
• --zone-mac <ZONE_MAC> Zone MAC Address.
• --mtu <MTU> Zone MTU.

kernel-events

Manage kernel events from zones.

protect zone kernel-events <COMMAND>

Subcommands:

• stream Stream kernel events from a zone.
• list-syscalls List all available syscalls.

kernel-events stream

Stream kernel events from a zone.

protect zone kernel-events stream [OPTIONS] <ZONE>

Arguments:

• <ZONE> Zone to show logs for, either the name or the uuid.

Options:

• -e, --enabled-events <ENABLED_EVENTS> Zone event types (syscall ids, etc) to enable notifications for.

kernel-events list-syscalls

List all available syscalls.

protect zone kernel-events list-syscalls

workload

Manage the workloads on Edera Protect.

protect workload <COMMAND>

Subcommands:

• launch Launch a new workload.
• exec Execute a command inside the workload.
• attach Attach to a workload console.
• resolve Resolve a workload name to matching workload ids.
• start Start a workload.
• stop Stop a workload.
• destroy Destroy a workload.
• list List workload information.
• watch Watch for workload changes.

launch

Launch a new workload.

protect workload launch [OPTIONS] --zone <ZONE> <OCI> [COMMAND]...

Arguments:

• <OCI> Container image for zone to use.
• <COMMAND> Command to run the workload.

Options:

• --image-format <IMAGE_FORMAT> Image format [default value: squashfs] [possible values: squashfs].
• --pull-overwrite-cache Overwrite image cache on pull.
• --pull-update Update image on pull.
• -n, --name <NAME> Name of the workload.
• -W, --wait Wait for the workload to be started.
• -t, --tty Allocate tty for the workload.
• -a, --attach Attach to workload console.
• --disable-all-namespaces Disable all process namespaces.
• --disable-namespace <DISABLE_NAMESPACE> Process namespaces to disable [possible values: mount, uts, ipc, user, pid, net, cgroup, time].
• --strict-user-namespace Enable strictness of user namespaces on the workload.
• --read-only-rootfs Enable read-only rootfs.
• --no-new-privs Prevent workload from requesting new privileges after launch.
• -e, --env <ENV> Environment variables set in the workload.
• -m, --mounts <MOUNTS> Mount host directories into the workload (in the form src=<HOSTDIR>:dst=<WORKLOAD_PATH>[:ro=true]).
• -b, --block-device <BLOCK_DEVICE> Mount host block device into the workload (in the form src=<HOSTDEV>:dst=<WORKLOAD_PATH>[:ro=true]).
• --cap-add <CAP_ADD> Capabilities to add.
• --cap-ambient-add <CAP_AMBIENT_ADD> Ambient capabilities to add.
• --cap-drop <CAP_DROP> Capabilities to drop.
• --privileged Run workload with elevated privileges.
• -w, --working-directory <WORKING_DIRECTORY> Working directory.
• --user <USER> User name or id.
• --group <GROUP> Group name or id.
• -z, --zone <ZONE> Zone to launch on, can be a name or id.
• --mount-scratch-disk <MOUNT_SCRATCH_DISK> Mount zone scratch disk on a certain directory.
• --hostname <HOSTNAME> Hostname inside the workload.
• --pci-device <PCI_DEVICE> PCI devices to attach to the workload.

exec

Execute a command inside the workload.

protect workload exec [OPTIONS] <WORKLOAD> [COMMAND]...

Arguments:

• <WORKLOAD> Workload to exec inside, either the name or the uuid.
• <COMMAND> Command to run inside the zone.

Options:

• -e, --env <ENV> Environment variables.
• -w, --working-directory <WORKING_DIRECTORY> Working directory.
• -t, --tty Allocate tty.
• --user <USER> User name or id.
• --group <GROUP> Group name or id.
• --privileged Execute with elevated privileges.

attach

Attach to a workload console.

protect workload attach <WORKLOAD>

Arguments:

• <WORKLOAD> Workload to attach to, either the name or the uuid.

resolve

Resolve a workload name to matching workload ids.

protect workload resolve [OPTIONS] <NAME>

Arguments:

• <NAME> The workload name to resolve.

Options:

• -f, --first If there are multiple matching workloads, only print the first workload id.

start

Start a workload.

protect workload start <WORKLOAD>

Arguments:

• <WORKLOAD> Workload to start, either the name or the uuid.

stop

Stop a workload.

protect workload stop <WORKLOAD> [TIMEOUT]

Arguments:

• <WORKLOAD> Workload to stop, either the name or the uuid.
• <TIMEOUT> How long to wait for the workload to stop (in seconds) before forcibly killing it, default 0.

destroy

Destroy a workload.

protect workload destroy [OPTIONS] [WORKLOAD_IDENTIFIER]

Arguments:

• <WORKLOAD_IDENTIFIER> Workload to destroy, either the name or the uuid. Optional when --selector is specified.

Options:

• -W, --wait Wait for the destruction of the workload to complete.
• -a, --all Destroy all workloads matching the input.
• -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘running’, ‘completed’, ‘destroying’, ‘destroyed’ and ‘failed’, with or without the ‘workload_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=WORKLOAD_STATE_FAILED).

list

List workload information.

protect workload list [OPTIONS] [WORKLOAD]

Arguments:

• <WORKLOAD> Limit to a single workload, either the name or the uuid.

Options:

• -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].
• -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘running’, ‘completed’, ‘destroying’, ‘destroyed’ and ‘failed’, with or without the ‘workload_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=WORKLOAD_STATE_FAILED).

watch

Watch for workload changes.

protect workload watch [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, json, key-value].

image

Manage the images on Edera Protect.

protect image <COMMAND>

Subcommands:

• pull Pull an image into the cache.
• import Import an image into the cache.
• remove Remove an image from the cache.
• list List cached images.

pull

Pull an image into the cache.

protect image pull [OPTIONS] <IMAGE>

Arguments:

• <IMAGE> Image name.

Options:

• -s, --image-format <IMAGE_FORMAT> Image format [default value: squashfs] [possible values: squashfs, tar, directory].
• -n, --no-update Don’t update from registry.
• -o, --overwrite-cache Overwrite image cache.
• -U, --username <USERNAME> Auth username.
• -P, --password <PASSWORD> Auth password.
• -T, --registry-token <REGISTRY_TOKEN> Auth registry token.
• --identity-token <IDENTITY_TOKEN> Auth identity token.

import

Import an image into the cache.

protect image import [OPTIONS] --digest <DIGEST> --image <IMAGE>

Options:

• -d, --digest <DIGEST> Image digest.
• -n, --image <IMAGE> Image name.
• -s, --image-format <IMAGE_FORMAT> Image format [default value: squashfs] [possible values: squashfs, tar, directory].
• -o, --overwrite-cache Overwrite image cache.
• -i <INPUT_FILE> Input image tar [default value: /dev/stdin].

remove

Remove an image from the cache.

protect image remove [OPTIONS] <DIGEST>

Arguments:

• <DIGEST> Image digest.

Options:

• -s, --image-format <IMAGE_FORMAT> Image format [default value: all] [possible values: all, squashfs, tar, directory].

list

List cached images.

protect image list [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].

network

Manage the network on Edera Protect.

protect network <COMMAND>

Subcommands:

• reservation Manage network reservations.

reservation

Manage network reservations.

protect network reservation <COMMAND>

Subcommands:

• create Create network reservation.
• destroy Destroy network reservation.
• list List network reservation information.

reservation create

Create network reservation.

protect network reservation create

reservation destroy

Destroy network reservation.

protect network reservation destroy <RESERVATION>

Arguments:

• <RESERVATION> Reservation to destroy.

reservation list

List network reservation information.

protect network reservation list [OPTIONS]

Options:

device

Manage the devices on Edera Protect.

protect device <COMMAND>

Subcommands:

• list List device information.

list

List device information.

protect device list [OPTIONS]

Options:

host

Manage the host of Edera Protect.

protect host <COMMAND>

Subcommands:

• cpu-topology Display information about the host CPU topology.
• status Get information about the host.
• control-snoop Snoop on the Control API.
• idm-snoop Snoop on the IDM bus.
• hv-console Display hypervisor console output.
• hv-debug-info Read hypervisor debug information.

cpu-topology

Display information about the host CPU topology.

protect host cpu-topology [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value].

status

Get information about the host.

protect host status [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, json, json-pretty, yaml, key-value].

control-snoop

Snoop on the Control API.

protect host control-snoop [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, jsonl, key-value].
• --filter-internals Filters out user agents matching edera-protect-*, excluding the CLI.

idm-snoop

Snoop on the IDM bus.

protect host idm-snoop [OPTIONS]

Options:

• -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, jsonl, key-value].

hv-console

Display hypervisor console output.

protect host hv-console

hv-debug-info

Read hypervisor debug information.

protect host hv-debug-info

completion

Output shell completion code for the specified shell.

protect completion <SHELL>

Arguments:

• <SHELL> [possible values: bash, elvish, fish, powershell, zsh].

Last updated on 2026-06-24

We use analytics to understand how people use our docs. No personal data is collected.