Usage¶

First, start QEMU with:

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

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

> qmp-shell ./qmp-sock

Syntax¶

Commands have the following 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, without spaces. Dictionaries/objects {} are supported, as 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). Both paradigms of literal values are accepted, including null/true/false for JSON and None/True/False for Python.

Transactions¶

Transactions have the following 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)

Commands¶

Autocomplete of command names using <tab> is supported. Pressing <tab> at a blank CLI prompt will show you a list of all available commands that the connected QEMU instance supports.

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. To check for new events from the server, press <enter> on a blank line:

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


 'event': 'STOP'}

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 useful for debugging to see the wire-level QMP data being exchanged, and generating output for use in writing documentation for QEMU.