Graphical Console

Use the graphical console to inspect and invoke supported session API methods.

The graphical console is available in a running Gnoblin session.

Graphical console

With the built-in configuration, Alt+F2 opens the compositor's Lua console. Alt+F2 or Escape closes it. It drops down from the top of the screen over every application and shell layer, with the input line at the bottom. The rest of the screen is dimmed behind it.

Output grows upwards from the input line. Scroll it with the mouse wheel or Page Up and Page Down. Enter runs a command and Shift+Enter inserts a newline.

The input line supports the usual editing keys:

• Ctrl+A selects everything.
• Ctrl+C, Ctrl+X and Ctrl+V copy, cut and paste through the system clipboard.
• Ctrl+Z and Ctrl+Y undo and redo.

Right-click the input line for a menu with Cut, Copy, Paste, Select All and Clear. A multi-line paste keeps its newlines and stays in the input until you press Enter.

While the console is open it is modal: keyboard shortcuts and keybindings do not run, and every key goes to the console. Ctrl+Alt+F1 to F12 still switch to another virtual console. Escape and Alt+F2 close it even if you have bound the console to another key.

Pointer and touch input does not reach windows or shell surfaces while the console is open, and they lose their hover state.

gnoblin.console.toggle() (Native API 1.77+) takes no arguments and queues a visibility toggle. It is unavailable while the session is locked. Bind it in a loaded Lua config:

gnoblin.configure {
    keybindings = {
        keyboard = {
            console = {
                binding = "<Alt>F2",
                callback = function() gnoblin.console.toggle() end,
            },
        },
    },
}

Run gnoblinctl reload after saving. The console evaluates Lua against the active configuration runtime and sends reload requests through compositor control.

Change settings

Call gnoblin.configure to change a setting in the running session:

gnoblin.configure { window_management = { focus_mode = "sloppy" } }

The call returns an Operation. It succeeds when the compositor commits the change. The change applies at once and lasts until the configuration is reloaded, so it does not edit your config files. A value the configuration does not accept is rejected with the reason, and the settings stay as they were.

Assigning to gnoblin.config raises an error that points to gnoblin.configure. Read the committed settings from gnoblin.settings. For a value that you want to take back, use gnoblin.settings.override(path, value).

Suggestions appear below the input as you type. Completion supports globals and dotted member names, such as gnoblin.windows.. It does not evaluate the input or call Lua getters.

Each function in the list shows its signature, such as (id: string): Window|nil, and a panel below the list describes the highlighted one, including the keys of a table argument.

Typing a call, for example gnoblin.workspaces.create(, shows that function's parameters under the input with the current one marked. Inside a table argument, the keys it accepts are suggested.

Press Tab to take the highlighted suggestion, or Shift+Tab to move up the list. Use Up and Down to move through the list; Enter then takes the chosen suggestion, and otherwise runs what you typed. Escape hides the list.

A result that is a table or window record starts collapsed. Click its row, anywhere across the width, to expand it. Entries are listed alphabetically, and the summary on the row lists as many as fit the width.

Functions show their signature, for example fn(filter?: WindowFilter): Window[]. A ? marks an optional argument. A function written in Lua shows its parameter names, and a function without a known signature shows as fn. For editor completion outside the console, see Editor support.

Expanded entries are read-only and limited to eight levels and 4,000 entries. A table cut off by that limit ends with a line such as … 12 more, which gives the number left out. A table that contains itself is marked (circular). Expanding does not execute Lua code. Errors show the message alone, for example attempt to index a nil value.

It keeps the last 200 submitted commands in $XDG_STATE_HOME/gnoblin/console-history.ini, or ~/.local/state/gnoblin/console-history.ini when XDG_STATE_HOME is unset. The history is diagnostic state, separate from the Lua configuration. Its file is written asynchronously after a submitted command.