CLI v1.3.0

10 min read

Using the CLI

Control the Edera Protect daemon.

 protect [OPTIONS] <COMMAND>

This CLI is under active development. Options and Commands are subject to change.

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.

Options:

• -c, --connection <CONNECTION> The connection URL to the Edera Protect daemon [default value: unix:///var/lib/edera/protect/daemon.socket].

zone

Manage the zones on Edera Protect.

 protect zone <COMMAND>

Subcommands:

• attach Attach to the zone console.
• list List zone information.
• launch Launch a new zone.
• destroy Destroy a zone.
• exec Execute a command inside the zone.
• 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.

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

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-append <KERNEL_CMDLINE_APPEND> Additional kernel cmdline options.
• --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: pv, pvh].
• -N, --network-backend <NETWORK_BACKEND> Network backend [possible values: default, none, external].

destroy

Destroy a zone.

 protect zone destroy [OPTIONS] <ZONE>

Arguments:

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

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’, ’exited’, ‘destroying’, ‘destroyed’ and ‘failed’, with or without the ‘zone state’ prefix. (e.g. --selector status.state=failed or --selector status.state=ZONE_STATE_FAILED).

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.

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.

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.
• 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, erofs]

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

• --strict-user-namespace Enable strictness of user namespaces on the workload.

• -e, --env <ENV> Environment variables set in the workload.

• -m, --mounts <MOUNTS> Mount host directories into the workload.

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

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.

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>

Arguments:

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

destroy

Destroy a workload

 protect workload destroy [OPTIONS] <WORKLOAD>

Arguments:

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

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, erofs, tar, directory].
• -n, --no-update Don't update from registry.
• -o, --overwrite-cache Overwrite image cache.

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, erofs, 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: squashfs] [possible values: squashfs, erofs, 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:

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

device

Manage the devices on Edera Protect.

 protect device <COMMAND>

Subcommands:

• list List device information.

list

List device information.

 protect device list [OPTIONS]

Options:

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

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.
• 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].

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-02-18.