QMP-SHELL(1)

✨ NAME ✨

qmp-shell — an interactive QEMU shell powered by QMP 💖

---

🌸 SYNOPSIS 🌸

qmp-shell [-h] [-H] [-v] [-p] [-l LOGFILE] [-N] qmp_server

---

🦋 DESCRIPTION 🦋

okay so picture this: qmp-shell hands you a cute lil shell with a shorthand syntax so you don't have to hand-type raw JSON like some sort of medieval scribe. it's giving convenience, it's giving main character energy. 🎀

BUT — and this is the important part bestie — this syntax is not standardized and it is not meant to be used as a scriptable interface. like, at all. the shorthand may change incompatibly in the future, no cap. so if you need API-stable scripting, please please please use the QMP library instead. the shell is for vibing interactively, not for building your CI on. 🙈

🧸 positional arguments:

• qmp_server — < UNIX socket path | TCP address:port > — that's where you point her, bestie.

🎀 optional arguments:

• -h, --help — show this help message and exit. the classic. iconic.
• -H, --hmp — Use HMP interface.
• -v, --verbose — Verbose (echo commands sent and received). she'll narrate everything 💅
• -p, --pretty — Pretty-print JSON. your eyeballs will thank you.
• -l LOGFILE, --logfile LOGFILE — Save log of all QMP messages to PATH.
• -N, --skip-negotiation — Skip negotiate (for qemu-ga).

---

🚀 Usage

first things first, start QEMU like this:

> qemu [...] -qmp unix:./qmp-sock,server=on[,wait=off]

then run the shell, passing the address of the socket:

> qmp-shell ./qmp-sock

boom. you're in. 🫶

---

✍️ Syntax

commands have this format:

< command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]

for example, to add a network device:

(QEMU) device_add driver=e1000 id=net1
{'return': {}}
(QEMU)

key=value pairs support either Python or JSON object literal notations — no spaces though, keep it tidy. Dictionaries/objects {} are supported, and so are arrays []:

example-command arg-name1={'key':'value','obj'={'prop':"value"}}

either JSON or Python formatting for compound values works, including both styles of string literal quotes (either single or double quotes, whatever feels right). and both paradigms of literal values are accepted: null/true/false for JSON, and None/True/False for Python. slay. ⭐

---

💸 Transactions

transactions have this multi-line format:

transaction(
action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
...
action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
)

one line transactions are also supported:

transaction( action-name1 ... )

for example:

(QEMU) transaction(
TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
TRANS> )
{"return": {}}
(QEMU)

look at her go 😭💖

---

🔮 Commands

Autocomplete of command names using tab is supported. and ooh — pressing tab at a blank CLI prompt will show you a list of all available commands that the connected QEMU instance supports. it's a whole menu, bestie. 👑

for documentation on QMP commands and their arguments, please see qmp ref.

---

🔔 Events

qmp-shell will display events received from the server, but this version does not do so asynchronously. so to check for new events from the server, press enter on a blank line:

(QEMU) ⏎
{'timestamp': {'seconds': 1660071944, 'microseconds': 184667},
 'event': 'STOP'}

not asynchronous, fr fr — you gotta poke her for the tea. ☕

---

🎨 Display options

use the -v and -p options to activate the verbose and pretty-print options, which will echo back the properly formatted JSON-compliant QMP that is being sent to QEMU. this is so useful for debugging so you can see the wire-level QMP data being exchanged, and for generating output to use when writing documentation for QEMU. chef's kiss. 💅✨

---

👑 Author

The QEMU Project authors

📜 Copyright

2009-2022, QEMU Project

---

okay that's the whole thing, bestie — this was unknown version, dated Apr 03, 2026, brought to you by the QEMU Monitor Protocol Library at QMP-SHELL(1). go forth and talk to your QEMU. periodt. 💖🌈🎀