Images

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

import

Import a VM image either from a VMFile definition or directly from a raw disk image file. For a VMFile, the CLI reads the manifest, validates it with the daemon, resolves the referenced disk image path, and streams the disk image to the daemon in chunks via gRPC.

vmr import <VMFILE|IMAGE_PATH> [OPTIONS]

Arguments

Argument	Description
VMFILE|IMAGE_PATH	Path to a VMFile (e.g., ./VMFile) or a disk image (e.g., ./image.qcow2)

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
--format <FORMAT>		Disk format (qcow2, raw, vmdk, vdi, vhdx) — required for direct import
--name <NAME>		Image name (e.g., test-image or user/test-image) — required for direct import
--cpus <CPUS>		CPU count for direct import (default: 2)
--memory <MIB>		Memory in MiB for direct import (default: 2048)
--bootloader <TYPE>		Bootloader for direct import: bios or uefi (default: bios)

A direct disk-image import is triggered by passing --format or --name; otherwise the path is treated as a VMFile.

Examples

# VMFile-driven import
vmr import ./VMFile -t latest

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

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

# Direct disk-image import (no VMFile)
vmr import ./disk.qcow2 --format qcow2 --name myuser/my-vm --cpus 4 --memory 4096 -t latest

# VMFile with a remote diskImageSource — the daemon downloads the image itself
vmr import ./VMFile -t latest

TIP

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

TIP

A VMFile can reference a disk image by URL instead of a local path with spec.diskImageSource. In that mode vmr uploads nothing — the daemon fetches and verifies the image directly against the required sha256 checksum.

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

overlay

Manage overlay images — images derived from a base image that store only the delta from that base (created with vmr commit --base). Overlays keep derived images small by sharing the base image's data.

vmr overlay <COMMAND>

Subcommands

Subcommand	Description
ls	List overlay images
inspect <NAME[:TAG]>	Show details about an overlay image

Options

Command	Flag	Short	Description
overlay ls	--names-only	-q	Print only overlay names (NAME:TAG), one per line

Examples

vmr overlay ls

vmr overlay inspect my-ubuntu:patched

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.