Configuration guide

The configuration directory

All Vesper configuration files live in ~/.config/vesper/. Vesper loads configurations in a specific order: internal defaults are loaded first, then `config.ini`, and finally `init.lua`, with later files overriding earlier ones.

The simple way: `config.ini`

For most common settings, the INI file is the easiest way to customize Vesper. Just create a file at ~/.config/vesper/config.ini and add the settings you want to change.

For example, to change the prefix key from `Ctrl-a` to `Ctrl-b`:

[general]
prefix = C-b

The powerful way: `init.lua`

For complete control, you can use a Lua script at ~/.config/vesper/init.lua. This file gives you access to the full Vesper API, allowing you to create custom commands, automate layouts, and much more.

For example, to create a new keybinding that opens a floating pane and runs `htop`:

-- This is a simplified example
        vesper.keymap.register("n", "t", function()
            local pane = vesper.panes.create({ floating = true })
            vesper.panes.send_keys(pane.id, "htop\n")
        end)

To see all available functions and modules, dive into the complete API reference.

Automating environments with `env.lua`

Vesper also supports a special script at ~/.config/vesper/env.lua that runs once at startup. This allows you to programmatically define a set of environment variables that will be applied to every new pane.

This is the perfect way to securely manage API keys and other secrets. We've written a detailed guide on this powerful feature.