microsoft/openvmm

# hypestv

`hypestv` is an interactive command-line interface for Hyper-V VMs, designed for
making OpenHCL developers' lives easier.

Similar to [`ohcldiag-dev`][], it can interact with the OpenHCL paravisor
running inside a Hyper-V VM. But unlike `ohcldiag-dev`, it sports an interactive
terminal interface (with history and tab completion), and it is specifically
designed to interact with Hyper-VMs.

[`ohcldiag-dev`]: ../../reference/openhcl/diag/ohcldiag_dev.md

In many ways, it is similar to the OpenVMM interactive console. In time, it may
end up sharing code and capabilities with it and with `ohcldiag-dev`, but it
will always be a Hyper-V specific tool.

Currently, it can:

* Change VM state (starting/stopping/resetting)
* Enable serial port output
* Inspect paravisor state

In the future, it might be able to:

* Enable paravisor and Hyper-V log output
* Enable serial port input
* Capture serial port output to another terminal window or file
* Inspect host state
* Persistence workspaces (save/restore configured serial ports and logs)

## Example session

`hypestv` launches into a detached mode, unless you specify a VM name on the
command line. To select a VM to work on, the VM named `tdxvm` in this example,
use the `select` command. If successful, you will now see the name and VM state
in the prompt:

```
> select tdxvm
tdxvm [off]>
```

After this, all commands will implicitly operate on `tdxvm`. Use `select` again
to work on another VM.

To enable serial port output, use the `serial` command. This can be used at any
time, even while the VM is not running. E.g., to enable serial port output for
COM2:

```
tdxvm [off]> serial 2 output
```

Start a VM with `start`. This is an asynchronous command: you can continue to
type other commands at the prompt while the VM starts. You should see an output
message when the VM finishes starting, as well as output about any configured
serial ports connecting.

Note that, due to limitations of the `rustyline` crate, the displayed VM state
on the prompt may not be accurate until you type another command or press Enter.

```
tdxvm [off]> start
serial port 2 connected
VM started
tdxvm [off]>
tdxvm [running]>
```

At this point, the VM is running, including the paravisor (if one is
configured). As in the OpenVMM interactive console, you can inspect paravisor
state with the `inspect` or `x` command, passing `-p` to specify that you want
to inspect paravisor state:

```
tdxvm [running]> x -p
{
    build_info: _,
    control_state: "started",
    mesh: _,
    proc: _,
    trace: _,
    uhdiag: _,
    vm: _,
}
```

You can terminate the VM with `kill`. This will disconnect any connected serial
ports as well, but they will reconnect next time the VM starts. Killing a VM
does not detach/deselect it; subsequent commands will continue to operate on the
VM.

```
tdxvm [running]> kill
serial port 2 disconnected
VM killed
tdxvm [stopping]>
tdxvm [off]>
```