Documentation & CLI Reference
Bootscry is a Python prototype. Its public repository is planned; these notes describe the current private code and its command-line interface. One command line and one MCP server drive every device that has a driver.
Installation & Setup (Planned Release)
The Bootscry public repository and package are planned. Until then, approved pilots with access to the private source install from a checkout. Requires Python >=3.11.
# For approved pilots with access to the private source:
cd bootscry
python3 -m pip install -e .Set your KVM password in your local environment without recording it in your shell history:
read -r -s -p "KVM password: " KVM1_PASSWORD
echo
export KVM1_PASSWORDCheck the device. For the Comet and other kvmd-based devices, the first connection pins the certificate fingerprint to ~/.config/glkvm/pins.json:
bootscry-kvm status--device picks the driver: comet (the default), nanokvm, pikvm, rfb for VNC consoles, or idrac for Dell iDRAC9 screenshots. What each has actually been run on is on supported devices. Each driver reads its own address and password variables from the environment.
CLI Reference (bootscry-kvm)
A selection of commands. bootscry-kvm --help lists all of them, including virtual media, payload images, session videos and key shortcuts for Linux, Windows and macOS targets.
| Command | Description | Example |
|---|---|---|
status | What the device is, what it sees, and whether the target sees a keyboard. | bootscry-kvm status |
snapshot | Saves the current frame. On the Comet, the first request wakes a sleeping streamer. | bootscry-kvm snapshot -o screen.jpg |
ocr | Reads the text on the screen with the readers in BOOTSCRY_READERS, in order. | bootscry-kvm ocr |
wait-text | Waits until the screen shows text matching a regular expression, with a timeout. | bootscry-kvm wait-text 'login:' --timeout 60 |
find-text | Finds text on the screen and prints its boxes in pixels. | bootscry-kvm find-text 'Save & Exit' |
click-text | Finds text on the screen and clicks the middle of it. | bootscry-kvm click-text 'Options' --double |
type | Types text. --secret NAME types an environment variable's value without printing it. | bootscry-kvm type 'systemctl restart ssh' --enter |
cad | Sends the Ctrl+Alt+Del chord to reboot the target. | bootscry-kvm cad |
reboot-to | Reboots and taps a key through POST to catch the boot menu, BIOS setup or GRUB; can check the boot phase afterwards and retry. | bootscry-kvm reboot-to Delete --duration 25 |
diagnose | Reads the screen and the network together to say why a host is silent, optionally against its stored baseline. Read-only. | bootscry-kvm diagnose HOST --baseline NAME |
Other installed commands: bootscry-ocr reads a saved picture, with --all to compare every reader; bootscry-baseline records what the screen, ssh and the network each say about a healthy machine, privately; bootscry-mcp is the MCP server, at the read tier unless the operator raises it (see safety).
Offline Mock Testing
Pilots with source access can run the test suite without physical hardware. It uses mocks and local sockets and never contacts a device; tests that need Tesseract, ffmpeg, QEMU or a kvmd container skip when those are missing.
python3 -m pip install -e '.[test,mcp,video]'
python3 -m pytest -qThe mocks check API behavior and client handling. Several Comet behaviors are known only from source or reports and require separate live checks. Which platforms run the suite is on the platforms record.