Lua API reference

Vesper exposes a rich Lua API for deep customization. This document serves as the official reference for all available modules and functions.

Getting started

All API functions are available under the global vesper table. You can write your scripts in ~/.config/vesper/init.lua to have them loaded at startup.

Global `vesper` API

`vesper.notify(message)`

Displays a temporary notification message in the Vesper status bar. Useful for debugging your scripts.

message (string): The text to display.

-- Example:
vesper.notify("My script has loaded successfully!")

`vesper.panes` API

`vesper.panes.get_active() -> pane_object`

Returns the currently active pane object.

Returns (table): An object representing the active pane, with properties like `id`, `is_floating`, etc.

`vesper.panes.create(options) -> pane_object`

Creates a new pane. By default, it splits the active pane vertically.

options (table, optional): A table of options.
- direction (string): "vertical" or "horizontal".
- floating (boolean): If true, creates a new floating pane.
Returns (table): An object representing the newly created pane.

-- Example: Create a new floating pane
local new_pane = vesper.panes.create({ floating = true })
vesper.notify("Created new floating pane with ID: " .. new_pane.id)

`vesper.panes.send_keys(pane_id, keys)`

Sends a sequence of keys to a specific pane as if they were typed by the user.

pane_id (number): The ID of the target pane.
keys (string): The string of keys to send. Use `\n` for Enter.

-- Example: Run 'htop' in a new horizontal split
local pane = vesper.panes.create({ direction = "horizontal" })
vesper.panes.send_keys(pane.id, "htop\n")