Images

Commands for managing VM images — importing from VMFiles, pulling and pushing to registries, exporting, tagging, and cleanup.

import

Import a VM image from a VMFile definition. The CLI reads the VMFile, resolves the referenced disk image path, and streams the disk image to the daemon in chunks via gRPC.

vmr import <VMFILE> [OPTIONS]

Arguments

Argument	Description
VMFILE	Path to the VMFile (e.g., ./VMFile or ./MyImage.VMFile)

Options

Flag	Short	Description
--context <PATH>	-c	Context path for resolving relative paths in the VMFile
--tag <TAG>	-t	Tags to assign to the imported image (can be specified multiple times)
--force	-f	Force overwrite if an image with the same name already exists

Examples

vmr import ./VMFile -t latest

vmr import ./VMFile -t latest -t v1.0.0

vmr import ./MyImage.VMFile -c ./build-context -t latest -f

TIP

The disk image path in the VMFile can be relative (resolved from the VMFile's directory) or absolute. Use --context to override the base directory for relative path resolution.

images

List all locally stored VM images, showing repository name, tag, digest, size, and creation date.

vmr images

Examples

vmr images

pull

Pull a VM image from the remote registry to local storage. Requires authentication — run vmr login first.

vmr pull <NAME[:TAG]>

Arguments

Argument	Description
NAME[:TAG]	Image reference (e.g., myuser/my-vm:latest)

Examples

vmr pull myuser/my-vm:latest

vmr pull myuser/my-vm

WARNING

If no tag is specified, the behavior depends on the registry server's default tag resolution. It is recommended to always specify an explicit tag.

push

Push a locally stored VM image to the remote registry. Requires authentication — run vmr login first.

vmr push <NAME[:TAG]>

Arguments

Argument	Description
NAME[:TAG]	Image reference (e.g., myuser/my-vm:latest)

Examples

vmr push myuser/my-vm:latest

WARNING

Push access is controlled by ACL rules on the auth server. Your user account must have push permission for the target repository pattern.

export

Export a locally stored VM image to a file on disk.

vmr export <NAME[:TAG]> [OPTIONS]

Arguments

Argument	Description
NAME[:TAG]	Image reference to export

Options

Flag	Short	Description
--output <PATH>	-o	Export file path (required)
--format <FORMAT>	-f	Export format: tar.gz (default) or image

Examples

vmr export myuser/my-vm:latest -o ./my-vm-export.tar.gz

vmr export myuser/my-vm:latest -o ./my-vm.qcow2 -f image

manifest

Inspect the manifest of a locally stored VM image. Displays the full manifest JSON including blob digests and image configuration.

vmr manifest <NAME[:TAG]>

Arguments

Argument	Description
NAME[:TAG]	Image reference to inspect

Examples

vmr manifest myuser/my-vm:latest

tag

Tag an existing image with a new name and/or tag. This creates a new reference pointing to the same underlying image data without copying blobs.

vmr tag <SOURCE> <TARGET>

Arguments

Argument	Description
SOURCE	Source image reference (e.g., myuser/my-vm:latest)
TARGET	Target image reference (e.g., myuser/my-vm:v2.0)

Examples

vmr tag myuser/my-vm:latest myuser/my-vm:v1.0.0

vmr tag myuser/my-vm:latest production/my-vm:stable

rmi

Remove one or more locally stored images. This deletes the manifest and, unless other tags reference the same blobs, the underlying data.

vmr rmi <IMAGE>... [OPTIONS]

Arguments

Argument	Description
IMAGE	One or more image references to remove

Options

Flag	Short	Description
--force	-f	Force removal without confirmation

Examples

vmr rmi myuser/my-vm:latest

vmr rmi myuser/my-vm:v1.0 myuser/my-vm:v2.0 -f

gc

Run garbage collection to clean up orphaned blobs and manifests that are no longer referenced by any image tag.

vmr gc [OPTIONS]

Options

Flag	Short	Description
--dry-run		Show what would be deleted without actually deleting
--force	-f	Force cleanup even if potentially dangerous

Examples

vmr gc --dry-run

vmr gc

vmr gc -f

TIP

Run vmr gc --dry-run first to preview what will be removed. This is especially useful after bulk image deletions to reclaim disk space safely.