Skip to main content


Laurence MorganAbout 2 min


Full screen previews for files and command documentation


Murex's readline API supports full screen previews. For example when autocompleting command line parameters, if that parameter is a file then Murex can preview the contents if it is a text file or even an image.

This preview can also provide guides to command usage. Such as man pages or AI generated cheatsheets.


event onPreview name=(function|builtin|exec) { code block }

!event onPreview name[.function|.builtin|.exec]

Valid Interrupts

  • builtin Code to execute when previewing a builtin (for example, a murex-docs page)
  • exec Code to execute when previewing an external executable (for example, a man page)
  • function Code to execute when previewing a Murex function (for example, the function source code)


The following payload is passed to the function via STDIN:

    "Name": "",
    "Interrupt": {
        "Name": "",
        "Operation": "",
        "PreviewItem": "",
        "CmdLine": "",
        "Width": 80


This is the namespaced name -- ie the name and operation.


This is the name you specified when defining the event.


This is the interrupt you specified when defining the event.

Valid interrupt operation values are specified below.


This will be the command name. For example if the command line is sudo apt-get update then the PreviewItem value will be sudo.


This is the full command line in the preview prompt (ie what you've typed).


Width of the preview pane. Please note that this will differ from the terminal width due to borders surrounding the preview pane.

Event Return

$EVENT_RETURN, is a special variable that stores a writable structure to return back to the event caller.

The $EVENT_RETURN values available for this event are:

    "CacheCmdLine": false,
    "CacheTTL": 2592000,
    "Display": true,


Should the cache be unique to the command or include the full command line? You would generally only want CacheCmdLine to be true if the generated preview is unique to the full command line (eg an AI generated page based on the full command line) vs only specific to the command name (eg a man page).


This just defines how long to cache the results for this onPreview event for faster loading of onPreview events in the future.

CacheTTL takes an integer and is measured in seconds. It's default value is 30 days.


Defines whenever to output this event invocation.

Defaults to true.


Creating a basic event

event onPreview example=exec {
    -> set event
    out "Preview event for $(event.Interrupt.PreviewItem)"
    $EVENT_RETURN.CacheTTL = 0 # don't cache this response.


Murex's ChatGPT integration also uses this event. The source code can be found on Githubopen in new window, of viewed from the terminal via:

runtime --events -> [[ /onPreview/chatgpt.exec/Block ]]


Standard out and error

Stdout and stderr are both written to the preview pane. Output is stripped or any ANSI escape sequences and stderr isn't written in red.

Order of execution

Interrupts are run in alphabetical order. So an event named "alfa" would run before an event named "zulu". If you are writing multiple events and the order of execution matters, then you can prefix the names with a number, eg 10_jump


This event is namespaced as $(NAME).$(OPERATION).

For example, if an event in onPrompt was defined as example=eof then its namespace would be example.eof and thus a subsequent event with the same name but different operation, eg example=abort, would not overwrite the former event defined against the interrupt eof.

The reason for this namespacing is because you might legitimately want the same name for different operations (eg a smart prompt that has elements triggered from different interrupts).

See Also

This document was generated from builtins/events/onPreview/onpreview_doc.yamlopen in new window.

Last update:
Contributors: Laurence Morgan