CLI Commands

CLI Commands

guestkit and guestctl share one command surface. Full flags: guestkit --help · guestkit <cmd> --help. List everything: guestkit commands (alias command-catalog).

Deep docs: cli-guide · quick-reference.

Quick start

cargo install guestkit          # guestkit + guestctl

guestkit detect disk.qcow2
guestkit inspect disk.qcow2 -o json
guestkit doctor disk.qcow2 --target proxmox --explain
guestkit migrate-plan disk.vmdk --target kvm --export plan.yaml
guestctl tui disk.qcow2

Most inspect commands accept -o json / --json. Add --trace to see loop vs NBD.

Command groups

Group	Commands
Inspect	inspect, inspect-batch, detect, info, filesystems, packages, services/systemd-services, users, network, inventory, health
Files	list/ls, cat, search/grep, find/find-large, hash, copy/cp, download/upload (via extract/copy), explore/ex, disk-usage
Assurance	doctor, migrate-plan, migrate-assess, migrate-repair, policy, fleet, forensic-diff, repair, passport
Plans / rescue	plan generate|preview|apply|rollback, rescue -o … — see Day-Zero and Rescue
Security	secrets, malware, compliance, audit, harden, anomaly, hunt, threat-intel (via related cmds), cve/score family
Profiles	profile security|migration|performance|compliance|hardening|windows-migration
Disk ops	convert, create, check, usage, clone, snapshot, backup, optimize
Interactive	interactive/repl, shell, explore — see Interactive Mode
TUI	tui (guestctl tui / guestkit tui) — see TUI
Agent	agent, agent-proxy, agent-call, agent-inject — see Guest Agent
Systemd	systemd-journal, systemd-services, systemd-boot
Meta	commands, completion, cache-clear, cache-stats, ai (optional feature)

High-traffic recipes

# Boot gate in CI
guestkit doctor img.qcow2 --target proxmox -o json --fail-below 80

# Fix plan + apply
guestkit migrate-plan vm.vmdk --target proxmox --export plan.yaml
guestkit plan preview plan.yaml
guestkit plan apply plan.yaml --vm vm.qcow2 --yes

# Passport
guestkit passport emit vm.qcow2 --target kvm -o passport.json --bundle
guestkit passport verify passport.json --fail-below 80

# Fleet / drift
guestkit fleet analyze ./vms/
guestkit forensic-diff golden.qcow2 drifted.qcow2

# Day-0
guestkit rescue disk.qcow2 -o enable-ssh
guestkit plan generate win.qcow2 -p windows-rdp -o rdp.yaml

Formats & privileges

• Formats: QCOW2, VMDK, VDI, VHD/VHDX, RAW, IMG (auto-detect)
• Mount/repair often need root; host needs qemu-img, losetup, qemu-nbd
• Env vars: Environment Variables

Related wiki

Interactive Mode · TUI · Cutover Cookbook · Explore