Lua configuration & scripts

Where configuration runs#

Harness reads Lua 5.1 configuration from ~/.config/harness/init.lua. HARNESS_CONFIG overrides the path. Lua executes in the CLI, not inside HarnessDaemon; there is no automatic file watcher.

Check before you reload#

harness-cli config check
harness-cli config reload
# Check another file without replacing the default path:
harness-cli config check --file /absolute/path/to/init.lua

check reports the file path, whether it exists, and counts for bindings, removals, modes, and actions. A syntax error exits 1. A reload with a syntax error keeps the previous keymap; it does not partially replace it. Remote config reload is deliberately refused.

Use the API from Lua#

Every JSON API method has a Lua counterpart. harness.pane.split{ direction = "horizontal" } uses the same executor as harness.call("pane.split", { direction = "horizontal" }). Calls return a result table or nil, an error message, and an exit code.

local pane, message, status = harness.pane.view({})
if not pane then
  error(message or ("Harness call failed: " .. tostring(status)))
end
print("Connected to the current pane")

harness-cli do /absolute/path/to/inspect.lua

Use api list and api describe to discover the available methods and arguments. The script’s daemon context, including --host, determines where the call runs.

Configuration versus long-running scripts#

Bindings, modes, actions, and host definitions belong in configuration. Event subscriptions and waits belong in scripts or actions: harness.on in the config file is warned about and ignored.

Scripts can run from a file, inline with do -e, or from stdin with do -. --args supplies JSON as harness.args. A script registering event handlers stays running until harness.stop or interruption.

harness-cli keymap --json
harness-cli actions --json

Use the release-pinned Lua section of the command reference for the full signatures of bind, unbind, mode, action, host, queue, and invoke. Check the effective keymap after changing configuration so a new binding does not unexpectedly shadow a familiar shortcut.