Skip to content

CLI reference

Run syzqemuctl COMMAND --help for the options installed with your package. Command failures return a non-zero process status.

Global command

syzqemuctl [--version] COMMAND [ARGS]

--version prints the installed version and checks PyPI for a newer release.

Image commands

init

syzqemuctl init --images-home PATH [--force] [--wait] [--size MB]
                 [--distribution RELEASE]

Initialize configuration and create the default template. The default size is 3072 MB. New image homes default to Trixie. --distribution selects another Debian release; an omitted value preserves an existing default template's release. --wait performs template creation in the foreground.

create

syzqemuctl create NAME [--size MB] [--distribution RELEASE] [--force]

Create an image from the default or size-specific template. With a custom size or distribution, only an exact matching cache is reused. --force bypasses the cache and creates the target from scratch. Without --distribution, the default template's release is inherited.

list and status

syzqemuctl list
syzqemuctl status NAME

List managed images or inspect one image's creation and VM status. Distribution and recorded disk size are shown when available.

delete

syzqemuctl delete NAME

Delete a stopped image. The command refuses active or unverifiable VM and creation runtime.

VM lifecycle commands

run

syzqemuctl run NAME [--kernel PATH] [--port PORT] [--mem SIZE] [--smp N]
                       [--snapshot] [--kernel-args TEXT]
                       [--extra-kernel-args TEXT]

The kernel path is required on first boot and reused from the last boot script thereafter. --kernel-args replaces the complete guest command line; --extra-kernel-args appends to the saved or default value.

stop

syzqemuctl stop NAME [--wait] [--force] [--timeout SECONDS]

--wait polls until runtime artifacts disappear. --force additionally targets exact-image orphan QEMU processes. The default wait timeout is 20 seconds and matters only with --wait.

restart

syzqemuctl restart NAME

Stop a running VM and start it with the saved boot configuration. Snapshot mode is not inherited.

Guest I/O commands

exec

syzqemuctl exec [--timeout SECONDS] NAME "COMMAND"

Execute a command through SSH. The CLI treats a non-zero remote exit status as a failure and prints captured stdout and stderr.

cp

syzqemuctl cp [--timeout SECONDS] LOCAL_PATH NAME:REMOTE_PATH
syzqemuctl cp [--timeout SECONDS] NAME:REMOTE_PATH LOCAL_PATH

Copy files or directories recursively between the host and one VM. Direct VM-to-VM copies are not supported.

cleanup-guest

syzqemuctl cleanup-guest NAME [--timeout SECONDS]

Connect to a running VM as root and remove a conservative whitelist of common syzkaller and reproducer temporary artifacts under /root. The default total timeout is 20 seconds. Run this after the previous workload has stopped and before uploading a new PoC. The command does not target normal PoC names, coverage, logs, or /tmp content. The documented managed names are reserved for temporary artifacts. It does not stop the VM or clean host-side runtime resources.

The command exits non-zero when SSH is unavailable, the timeout expires, or one or more managed paths remain after the best-effort cleanup.

Diagnostics

syzqemuctl diagnose NAME [--timeout SECONDS] [--no-check-port] [--json]

Inspect runtime state without modifying it. --json is intended for scripts and agents. See Runtime diagnostics for field semantics.