Skip to main content

CLI reference (v1.3.0)

guestkit and guestctl are the same binary and share one command surface (guestctl is a symlink to guestkit in the release tarball). The separate guestkit-qemu binary plans and launches QEMU from the same assurance engine. Use guestkit --help, guestkit <command> --help, and guestkit-qemu --help for the authoritative flag list; this page summarises the command surface and links the curated docs.

Running guestkit <disk-image> with a single disk path (for example guestkit vm.qcow2) is shorthand for guestkit inspect vm.qcow2.

Quick start​

guestkit inspect disk.qcow2
guestkit doctor disk.qcow2 --target proxmox --explain
guestkit doctor disk.qcow2 --target proxmox -o json --fail-below 80
guestkit migrate-plan disk.qcow2 --target kvm --export plan.yaml
guestctl tui disk.qcow2
guestkit-qemu plan disk.qcow2 --json
guestkit-qemu run disk.qcow2 --min-boot-score 80
guestkit qga --execute guest-ping # needs a build with --features agent

guestkit-qemu and virtctl-guestkit are not in the release tarball (it ships guestkit and the guestctl symlink only). Build them from source with cargo build --release; see Prerequisites and build.

Where to look​

TopicDoc
Cheat sheetquick-reference.md
Install & buildgetting-started.md
Migration assurancemigration-assurance.md
QEMU / VirtIO runtimeqemu-runtime.md
Dump virsh → GuestKitvirsh-to-guestkit.md
Guest agentguest-agent.md
VM migration workflowsvm-migration.md
TUI keys & Assurancetui-enhancements.md
Fix plans & rescuefix-plans.md
Profilesprofiles.md
Interactive REPLinteractive-mode.md
File explorerEXPLORE-QUICKSTART.md
Cloud disk sourcescloud-disk-sources.md
Python APIpython-bindings.md
Serial console without grubbyimg-firstboot.md
FAQfaq.md
Troubleshootingtroubleshooting.md

Global flags​

These are accepted by every subcommand.

FlagMeaning
--verboseVerbose output (debug log level)
--debugShow internal operations (sets GUESTKIT_DEBUG=1)
-q, --quietSuppress non-error output (conflicts with --verbose)
--no-colorDisable colored output
--timestampsTimestamps in log output
--machine-readableImplies --no-color
-R, --read-onlyDocumented as "prevent write operations"; exports GUESTKIT_READONLY=1
-T, --timeout SECONDSDocumented as an operation timeout (0 = none); exports GUESTKIT_TIMEOUT
--cache-dir DIRRoot directory for all guestkit caches (also read from GUESTKIT_CACHE_DIR); default ~/.cache/guestkit
-j, --jobs NDocumented as parallel workers

Caveat from reading the v1.3.0 source: --read-only and --timeout only set the environment variables above, and nothing in the source reads GUESTKIT_READONLY or GUESTKIT_TIMEOUT; the global --jobs value is not read either. This was established by searching the code, not by running the binary. Do not rely on --read-only to protect an image: use read-only commands, guestkit doctor/inspect, or a copy of the disk. The per-command parallelism flags (fleet ... -j, inspect-batch --parallel) are separate per-command arguments. The inspection cache is ~/.cache/guestkit/ unless --cache-dir (or GUESTKIT_CACHE_DIR) points elsewhere.

--cache-dir DIR relocates every cache: inspection results (DIR/*.json), DIR/binary, the TUI per-image cache (DIR/<hash>), DIR/cve, DIR/packages, DIR/cloud, DIR/ai-memory and DIR/fleet-baseline. The per-subsystem overrides GUESTKIT_CLOUD_CACHE_DIR, GUESTKIT_AI_MEMORY_DIR and GUESTKIT_FLEET_BASELINE_DIR still take precedence for their own cache.

Command groups​

guestkit commands prints the grouped list that ships in your binary. The table below is checked against the clap definitions in src/cli/entry.rs for v1.3.0; aliases are in parentheses.

GroupCommands
Inspectinspect, inspect-batch, detect, info, filesystems (fs), packages (pkg), network, inventory, scan, diff, compare
Fileslist (ls), extract (get), cat, search (find), grep, hash, copy, backup, find-large, find-duplicates, diff-files, disk-usage, usage (df), check (fsck)
Disk imagesconvert, create, shrink, img (info, check, snapshots, snapshot-create, snapshot-delete, snapshot-apply, resize, rebase, commit), snapshot, clone, optimize, cache-clear, cache-stats
Assurancedoctor, migrate-plan, migrate-assess, migrate-repair, policy (check, rego), cloud-profile, fleet (analyze, wave-plan, watch, quarantine), forensic-diff, sbom-diff, gate, passport (emit, verify, show, diff, keygen, handoff)
Repair and rescuerepair, rescue, plan, harden, patch, sysprep, selinux-relabel, virtio-initramfs, firstboot, cloud-init, bitlocker (status, escrow), virtio-win (list, plan)
Security and compliancesecrets, compliance, malware, health, audit, anomaly, recommend, predict, hunt, reconstruct, evolve, verify
Live guest and runtimeqga, agent, agent-proxy, agent-call, agent-inject, agent-sign, vm, domain-disks, execute (exec)
Systemdsystemd-journal, systemd-services, systemd-boot
Interactivetui (ui), shell (sh), interactive (repl), explore (ex), script (batch), ai
Analysis and planninganalyze, benchmark, timeline, fingerprint, drift, validate, license, blueprint, migrate, cost, dependencies, intelligence, simulate, score, template
Utilitieshost-check, completion (bash, zsh, fish, powershell, elvish), commands, version, mcp-serve (needs the mcp feature)

There is no cp, download, upload or top-level profile command. Use copy (between two images), extract (guest to host) and plan/rescue/migrate-repair for writes. Inspection profiles are selected with inspect --profile (security, migration, performance, compliance, hardening, windows-migration).

Targets​

doctor, migrate-plan, migrate-assess, migrate-repair, passport emit and gate accept kvm, qemu, kubevirt, proxmox, hyperv, cloud, aws, azure and gcp. aws, azure and gcp score as cloud. An unknown name is not rejected: the boot engine falls back to a generic profile. --help for doctor lists only kvm, proxmox, hyperv, cloud.

Frequently used flags​

CommandFlags
inspect-o, --output text|json|yaml|csv, -p, --profile, -e, --export html|markdown|pdf, --export-output PATH, --no-cache, --cache-refresh, -S, --summary, --include-packages, --include-services, --include-network, --depth quick|standard|deep, --save-report FILE
doctor--target (default kvm), --explain, --ai (needs the ai feature), -o text|json, --fail-below SCORE (exit 1 under the score)
migrate-plan--target (required), --explain, --ai, -o text|json, --export FILE (YAML or JSON by extension), --inject-agent, --agent-binary, --agent-unit
migrate-assess--target, -o, --fail-below SCORE, --explain
host-check-o text|json|yaml, --strict (exit 1 on warnings too)
migrate-repair--target, --apply (takes a full-image backup first), --include-destructive, --virtio-win DIR, --export FILE
repair--fix boot or -t, --repair-type permissions|packages|network|bootloader|filesystem|boot (one is required), --dry-run, -f, -b, --inject-agent, --agent-binary, --agent-unit
rescue-o, --operation one of reset-password, fix-fstab, check-grub, fix-grub, enable-ssh, inject-ssh-key, set-hostname, enable-rdp, enable-winrm, set-timezone, install-packages; plus -u, -p, --key, --key-file, --hostname, --timezone, --packages a,b, --network, -f, -b, --export-plan PLAN.yaml
plangenerate (-p PROFILE: security (default), windows-rdp, windows-winrm, windows-hostname, windows-domain-leave, windows-timezone, windows-static-ip, windows-dhcp, windows-dns, windows-sysprep, linux-ssh, linux-hostname, linux-grub; -o FILE, -f yaml|json, plus profile options such as --user, --key, --key-file, --hostname, --workgroup, --timezone, --ip, --mask, --gateway, --dns, --interface-guid, --grub-timeout, --grub-cmdline), preview (-d, -s), validate, export (-f), apply (--vm, -n/--dry-run, -y, -i, -b DIR, --skip-backup), rollback
passportemit --target T -o FILE [--bundle] [--content-hash] [--virtio-win DIR] [--live-url URL] [--sign-key FILE] [--issuer NAME] [--expires-hours H], verify FILE [--fail-below S] [--require-signature] [--public-key HEX] [--trust-keys FILE] [--max-age-hours H], handoff, keygen
fleetanalyze DIR, wave-plan DIR, watch DIR (--reset-baseline, --fail-on-drift), quarantine DIR (--threshold, default 80, --fail); common flags -o text|json, --recursive, -j N
convert-o PATH, -f qcow2|raw|vmdk|vhd|vdi, -c, -F, -P, --verify, -S, --preallocate, --compression-level 1-9, --buffer-size MB
shrink--dry-run, --min-ratio (default 3.0), --headroom-pct (default 20), --json
qga--socket PATH (auto-discovered when omitted), --execute CMD, --arguments JSON, --raw JSON
gate--passport FILE or --image, --target, --fail-below (default 80), --sbom-old, --sbom-new, --rego FILE, -o

migrate-assess --explain appends a "path to ready": the failed checks ordered blockers first, then by score gain, with each fix's standalone gain, the cumulative score and readiness after applying it, and projected score/readiness once all blockers (and then all checks) are fixed. It replays the scoring over the assessment's own checks (no extra image access). With -o json the output gains an explain object (schema: "guestkit.assessment_explain/1"); without the flag the output is unchanged.

guestkit-qemu has three subcommands: plan IMAGE, run IMAGE (--min-boot-score, default 70; --allow-unready) and qmp --socket PATH status|pause|resume|powerdown|quit|balloon MIB. See qemu-runtime.md.

What the release binary includes​

The GitHub Release tarballs (guestkit-<version>-linux-amd64.tar.gz and the static -musl variant) are built with the guestkit binary only. The glibc build uses the default features (plus registry-write when libhivex was available at build time); the musl build uses --no-default-features --features guest-inspect (no libhivex, no libsystemd). Some commands exist in the CLI but need a feature that those builds do not enable:

FeatureNeeded for
agent (Unix)qga, agent, agent-proxy, agent-call, agent-inject, agent-sign, passport keygen, passport emit --sign-key, and the --agent-binary / --agent-unit options of repair --fix boot and migrate-plan
aidoctor --ai, migrate-plan --ai, ai
mcpmcp-serve (or use the ghcr.io/zyvorai/guestkit-mcp image)
registry-writeOffline Windows registry hive writes: the AES SAM hash path of rescue -o reset-password on Windows, agent-inject --windows, and (together with agent) offline DriverInject of VirtIO drivers when a plan is applied (plan apply). Without both features a DriverInject operation is skipped with a warning. glibc tarball only, and only if libhivex was present at build time
cloud-s3, cloud-azure, cloud-gcs (cloud for all three)s3://, Azure and gs:// disk sources, see cloud-disk-sources.md

guestkit host-check answers "can this machine run guestkit?" before you point it at an image. It is offline and read-only, and checks: qemu-img on PATH (failure if missing), qemu-nbd, losetup, mount and blkid (warnings), the nbd and loop kernel modules (/sys/module), whether you are root, a writable NBD lock directory (/run/lock or $XDG_RUNTIME_DIR) and a writable cache directory (--cache-dir / GUESTKIT_CACHE_DIR, else ~/.cache/guestkit). It exits 1 on any failure (or any warning with --strict), so it can gate provisioning scripts and CI images:

guestkit host-check
guestkit host-check -o json --strict

Rebuild with cargo build --release --features agent,ai,mcp,cloud (or the subset you need). The in-guest agent has its own artifact: zyvor-vm-tools-linux-amd64.tar.gz and the .deb on the same release.

Safety behaviour you should know about​

These are the v1.2.11 behaviours that affect how you run the CLI against images you do not fully trust. Details are in the changelog.

  • Chroot-style path resolution. Guest paths handed to the file operations (cat, list, extract, copy, plan apply, and so on) are resolved inside the guest root. An absolute guest symlink restarts at the guest root instead of pointing at your host, .. never climbs above the root, and a dangling absolute symlink can no longer make a write land on a host path. File names that merely contain .. (for example app..log) are accepted.
  • nodev,nosuid mounts. Every host mount of a guest filesystem adds nodev,nosuid (appended last, so it overrides a caller-supplied dev or suid). Device nodes planted in an image cannot open host devices through the mount.
  • cat and file reads. At most 1 GiB is read, and FIFOs, device nodes and directories are refused (a planted FIFO used to block forever).
  • grep. The pattern is passed after -e and --, so a pattern starting with - is searched for, not parsed as a grep option.
  • Mount points and archives. .. in a mount point is rejected; tar/archive directory arguments are confined to the guest root; cpio extraction refuses absolute and .. member names.
  • glob_expand, grub_update, selinux_relabel use the guest root mount, never an arbitrary mount; glob patterns containing .. are rejected and the results are guest paths.
  • Image paths are made absolute before they are handed to losetup, qemu-nbd and qemu-img, so a file named -x.img or json:{...} is not read as an option or protocol spec.
  • NBD allocation lock lives in /run/lock/guestkit-nbd.lock, then $XDG_RUNTIME_DIR or /run/user/<uid>; never /tmp. See Troubleshooting.
  • Binary cache directory is owner-only (0700); the fallback is /tmp/guestkit-<uid> and is refused when it is a symlink or owned by someone else.

guestkit execute (exec) is different: it runs the command with chroot into the mounted guest root on your host, as root, so it executes the image's own binaries. Only use it on images you trust.

Useful environment variables​

VariablePurpose
GUESTKIT_PACKAGE_CACHEHost dirs of .rpm/.deb for offline PackageInstall staging
GUESTKIT_PACKAGE_FETCH1/true — host-download missing packages before staging
GUESTKIT_PACKAGE_MIRRORHTTP base URL(s) for package fetch fallback (curl/wget)
GUESTKIT_VIRTIO_WINVirtIO driver tree for offline Windows DriverInject
GUESTKIT_FLEET_JOBSParallelism for fleet analyze (default min(4, CPUs))
GUESTKIT_FLEET_BASELINE_DIRWhere fleet watch stores per-VM golden baselines
GUESTKIT_S3_ENDPOINT / AWS_ENDPOINT_URLCustom S3-compatible endpoint for cloud disk pulls
GUESTKIT_CLOUD_CACHE_DIROverride ~/.cache/guestkit/cloud/
GUESTKIT_QEMU_IMGPath to the qemu-img binary used by guestkit img
GUESTKIT_DEBUG, GUESTKIT_TRACESet to 1 for debug or trace logging in the engine

The --debug global flag sets GUESTKIT_DEBUG for you; see the caveat under Global flags for the others.

Details: fix-plans.md, cloud-disk-sources.md.

Disk formats​

QCOW2, VMDK, VDI, VHD, VHDX, RAW, IMG — detected from the file header (not the extension; v1.2.10 added VHDX, VDI, dynamic VHD and VMDK descriptor images). RAW/IMG/ISO use loop devices; the other formats use qemu-nbd and the nbd kernel module. Use --debug to see which path is used. Attaching a disk needs root (GuestKit uses sudo when it is not root); on Ubuntu 26.04 the device nodes are root:disk 0660, see Prerequisites.

guestkit convert writes qcow2, raw, vmdk, vhd or vdi. The worker convert job (see offline repair worker) accepts raw, qcow2, qcow, vmdk, vdi, vhd, vpc, vhdx, qed and parallels, and refuses an output path equal to the source image.

JSON output​

Most inspect commands accept -o json or --json for scripting. See quick-reference.md for examples.

The assurance commands doctor, migrate-plan, migrate-assess, forensic-diff, fleet (analyze, wave-plan, watch, quarantine) and passport diff take -o text|json|yaml. The YAML document has the same structure as the JSON one, so -o yaml is handy for diffing in Git or feeding tools that prefer YAML. An unknown format (for example -o jsno) is now an error, checked before the image is opened, instead of silently printing text.

See also​