execute-lua - SKILL.md Agent Skill

name: execute-lua description: > Use this skill when you need to execute, test, or debug Lua code inside Neovim's runtime environment without opening the editor UI. Applies when: inspecting plugin modules (e.g. `require "octo.gh"`), verifying API behaviour, reproducing bugs, running one-off scripts against plugin code, or checking what functions/tables a module exposes. Supports four modes: fully isolated (no config, simulates a fresh install), dependency-controlled (no config but explicit runtimepath), full user environment (real init.lua + lazy.nvim), and Plenary Busted test runner (relative paths, no filesystem assumptions). Prefer this over plain `lua` or `luajit` when the code uses `vim.*` APIs or depends on Neovim's plugin runtimepath.

When you need to exercise Lua code in the exact Neovim environment that the user has installed, shell out to nvim with the -es headless flags and pass a temporary Lua script via -l.

There are four distinct execution modes depending on the goal.

Finding the key paths

Before running any mode, resolve these paths and store them in shell variables. Run this once to discover them:

# Neovim config dir (where init.lua lives)
NVIM_CONFIG=$(nvim -es -u NONE -l <(echo 'print(vim.fn.stdpath("config"))'))
echo "Config: $NVIM_CONFIG"

# Plugin manager data dir (where lazy.nvim stores plugins)
PLUGIN_DATA=$(nvim -es -u NONE -l <(echo 'print(vim.fn.stdpath("data") .. "/lazy")'))
echo "Plugin data: $PLUGIN_DATA"

# Plugin root dir (run from the cloned repo)
PLUGIN_DIR=$(pwd)
echo "Plugin dir: $PLUGIN_DIR"

# Specific dep (e.g. plenary.nvim)
PLENARY_DIR="$PLUGIN_DATA/plenary.nvim"
echo "Plenary dir: $PLENARY_DIR"

The examples below use these variables. Substitute the actual paths if not using shell variables.

Mode 1: Isolated / Fresh-install simulation

No user config, no plugin manager. Only octo.nvim is added to runtimepath via --cmd. Use this to test the plugin in isolation, as if it were a fresh install.

cat <<'EOF' > /tmp/snippet.lua
local ok, gh = pcall(require, "octo.gh")
if ok then
  print(vim.inspect(gh))
else
  print("FAIL: " .. gh)
end
EOF

nvim -es -u NONE --cmd "set rtp+=$PLUGIN_DIR" -l /tmp/snippet.lua

-u NONE — skips all user config
--cmd "set rtp+=$PLUGIN_DIR" — injects the plugin dir before init, making its Lua modules findable
$PLUGIN_DIR comes from the discovery step above; replace with the actual path if not using shell variables

Mode 2: Script-controlled runtimepath

Same isolation as Mode 1 but the runtimepath is set from within the Lua script. Useful when you need multiple dependencies (e.g. plenary.nvim).

cat <<'EOF' > /tmp/snippet.lua
vim.opt.runtimepath:append(vim.fn.getcwd())
vim.opt.runtimepath:append(vim.fn.stdpath("data") .. "/lazy/plenary.nvim")

local ok, gh = pcall(require, "octo.gh")
if ok then
  print(vim.inspect(gh))
else
  print("FAIL: " .. gh)
end
EOF

nvim -es -u NONE -l /tmp/snippet.lua

vim.fn.getcwd() resolves to the plugin root if you run from within the repo
Dep paths use vim.fn.stdpath("data") — resolves to the correct location on any machine
List installed lazy plugins: ls ~/.local/share/nvim/lazy/

Mode 3: Full user environment

Loads the user's real init.lua (including lazy.nvim and all installed plugins). Use this to simulate exactly how the plugin behaves in the live setup.

cat <<'EOF' > /tmp/snippet.lua
local ok, gh = pcall(require, "octo.gh")
if ok then
  print(vim.inspect(gh))
else
  print("FAIL: " .. gh)
end
EOF

nvim -es -u "$NVIM_CONFIG/init.lua" -l /tmp/snippet.lua

Omit -u NONE and pass the real config path explicitly
$NVIM_CONFIG comes from the discovery step above; alternatively use $(nvim -es -u NONE -l <(echo 'print(vim.fn.stdpath("config"))'))
lazy.nvim runs during init, adding all plugins to runtimepath before the script executes
Note: lazy-loaded plugins (lazy = true) may not be available unless triggered with require("lazy").load({ plugins = { "plugin-name" } }) inside the script

Mode 4: Running Plenary Busted tests

Run the project's existing Plenary Busted test suite. All paths are relative to the plugin root (pwd), so no filesystem-specific configuration is needed.

# Run a single test file
nvim --headless -c "PlenaryBustedFile lua/tests/plenary/gh_graphql_spec.lua {minimal_init = 'lua/tests/minimal_init.vim'}"

# Run all tests in the directory
nvim --headless -c "PlenaryBustedDirectory lua/tests/plenary/ {minimal_init = 'lua/tests/minimal_init.vim'}"

Requires plenary.nvim to be on the runtimepath — the project's lua/tests/minimal_init.vim handles this via relative rtp entries (change those if plenary lives elsewhere).
PlenaryBustedFile and PlenaryBustedDirectory are commands provided by plugin/plenary.vim.
The minimal_init.vim path is relative and resolves from the cwd (plugin root).

Best Practices

Always wrap require in pcall for readable failure messages.
Use vim.print(x) instead of print(vim.inspect(x)) — it calls vim.inspect automatically.
Report: the exact command run, snippet path, exit code (echo "exit: $?"), and full stdout/stderr.
The working directory is wherever nvim is invoked; verify with print(vim.fn.getcwd()).