Execution Models
Matchmaker supports multiple execution strategies for running commands, generating input rows, copying text, transforming state, and executing actions.
IMPORTANT
However broad the following section is, for the most part it only exists so that matchmaker can act consistently with respect to Lua support. You can almost always just use simple inline scripts (the shell command strategy), for which you should consult the template docs instead.
Strategy Overview
Every command string (except preview layout commands) is classified into one of four execution strategies based on its prefix:
| Prefix / Shape | Strategy | Description |
|---|---|---|
command ... | Shell Command | Run via the configured shell (start.shell or $SHELL -c). Supports {} template expansions. |
@path [args...] | Script File | Runs path through the configured shell (start.shell or $SHELL) with args. Relative paths resolve against the preset's directory. |
@./path [args...] | Direct File | Executes the file at path itself (the kernel honors its shebang; the file must be executable). Relative paths resolve against the preset's directory. |
#!lua ... | Inline Lua | Runs inline Lua script on the internal Lua runtime with access to global state and env tables. |
@file.lua [args...] | Lua Script File | Runs file.lua on the internal Lua runtime, passing args as varargs (...). Relative paths resolve against the preset directory. |
NOTE
Lua strategies require the mlua cargo feature (enabled by default). When disabled, #!lua falls back to Shell, and @*.lua falls back to Direct File.
NOTE
Relative files resolve against the parent directory of MM_OVERRIDE. This is exactly the path of the first override passed with -o!
Feature & Action Support Matrix
Different contexts in Matchmaker use command strategies in specific ways:
| Context / Action | Shell | @file | #!lua | @file.lua | Output / Result Handling |
|---|---|---|---|---|---|
Execute, ExecuteSilent, ExecuteAsync, ExecuteThen | ✓ | ✓ | ✓ | ✓ | Exit code determining success / continuation |
ExecuteOrConfirm, ExecuteAndQuit | ✓ | ✓ | ✓ | ✓ | Exit code determining prompt vs. quit policy |
Become, BecomeSilent | ✓ | ✓ | — | — | Replaces Matchmaker process (exec) |
BecomeOrConfirm, BecomeOrResume | ✓ | ✓ | — | — | Replaces process with exit code recovery policy |
Copy, CopyAsync | ✓ | ✓ | ✓ | ✓ | Shell/File captures stdout; Lua uses script return value |
Transform, TransformConfig | ✓ | ✓ | ✓ | ✓ | Shell/File parses stdout; Lua parses script return value |
start.command & Reload / ReloadNext / ReloadPrev | ✓ | ✓ | ✓ | ✓ | Shell/File reads piped stdout; Lua calls global inject(line) |
start.directory (when exec = true) | ✓ | ✓ | ✓ | ✓ | Shell/File captures stdout; Lua uses script return value |
Dynamic [envs] (when exec = true) | ✓ | ✓ | ✓ | ✓ | Shell/File captures stdout; Lua uses script return value |
--list & --list=<ARG> | ✓ | ✓ | ✓ | ✓ | Runs command directly outside TUI |
preview.layout[].command | ✓ | — | — | — | Strictly Shell execution with {} template expansion |
Script File Execution (@)
Commands prefixed with @ run a file stored next to the preset:
[binds]
"ctrl-o" = "Execute(@open_file.sh {file})"
"ctrl-y" = "Copy(@format_item.py '{name}' '{path}')"- Path Resolution: Relative paths resolve against the directory of the first applied preset (
MM_OVERRIDEparent). Absolute paths are used as-is. - Argument Preservation: Arguments are split by whitespace. Single quotes (
'arg with spaces') preserve whitespace within arguments without shell interpolation. - Interpreter: The configured shell (
start.shellor$SHELL) reads the file as source in its own language; write the file in that shell's dialect, or use@./(below) to select the interpreter via shebang.
Direct File Execution (@./)
A path starting with ./ is executed through execve, so the kernel honors its shebang and the file runs under its declared interpreter:
[start]
command = "@./zellij.sh sessions"- Executable bit required: the file must be executable (
chmod +x); otherwise execution fails with a permission error. - Shebang honored:
@./script.shruns under the interpreter its shebang names -- use this for bash-specific syntax (arrays,export -f) or any interpreter other than the configured shell. .luafiles keep Lua-engine precedence:@./x.luaruns on the internal Lua runtime.
Lua Runtime (mlua)
Each Lua execution runs on a fresh, isolated Lua 5.4 VM. Concurrent actions (such as ExecuteAsync background tasks or ExecuteSilent threads) never share or block on VM state.
Inline Scripts (#!lua)
A payload starting with #!lua followed by whitespace runs the rest of the string as Lua code:
[binds]
"@open" = '''ExecuteOrConfirm(#!lua local p = state.current and state.current[1]
if p then
os.execute(string.format("%q -- %q", os.getenv("EDITOR") or "vi", p))
end)'''Script Files (@file.lua)
A @ path ending in .lua executes the file within the Lua engine:
[binds]
"@process" = "ExecuteAsync(@process_item.lua --fast)"Remaining words become varargs (...) passed to the script.
Input Stream Ingestion (inject)
For start.command and Reload, Lua scripts do not write to standard output. Instead, rows are pushed into Matchmaker using the global inject(line) function:
[start]
command = '''#!lua
for _, item in ipairs({ "apple", "banana", "cherry" }) do
inject(item)
end'''Or via a sibling file:
[start]
command = "@list_items.lua"The state Table
The global state table provides an execution-time snapshot of the picker:
| Field | Description |
|---|---|
state.query | Current user search query string |
state.mode | Comma-joined active mode tags |
state.raw | Complete raw line of the current item (nil if nothing selected) |
state.current | Current item columns array [1]...[n], also keyed by column names |
state.selected | Array of selected items (each item is a column array; mirrors {+}) |
state.position | 0-based index of current cursor item |
state.total | Total item count |
state.matched | Matched item count |
state.selected_count | Selected item count |
state.active | 1-based index of the focused column |
state.args | Trailing CLI arguments passed after -- (1-indexed array) |
#!lua
local selected_paths = {}
for _, item in ipairs(state.selected) do
if item.path then table.insert(selected_paths, item.path) end
end
return table.concat(selected_paths, "\n")The env Table
The global env table exposes environment variables to scripts (MM_*, FZF_*, and anything you define in [envs]):
local override_dir = env.MM_OVERRIDE and env.MM_OVERRIDE:match("(.*/)")To access the parent process environment variables (such as $EDITOR or $HOME), use standard Lua os.getenv("EDITOR").
Mode-Gated Lua Binds
Because Matchmaker appends a lua mode tag when mlua is enabled, you can provide Lua implementations that gracefully fall back when compiled without Lua:
[binds]
"@copy" = "Copy(echo -n {+})"
"lua^^@copy" = '''Copy(#!lua local t = {}
for _, it in ipairs(state.selected) do t[#t + 1] = it[1] end
return table.concat(t, "\n"))'''Exit Policies & Lifecycle Handling
What happens to the picker after a synchronous command exits depends on the action:
| Action | Success (exit 0) | Non-Zero Exit | Interrupted / Ctrl+C / Signal |
|---|---|---|---|
Execute | Returns to TUI | Returns to TUI | Returns to TUI |
ExecuteOrConfirm | Returns to TUI | Displays confirmation prompt | Returns to TUI (no prompt on signal) |
ExecuteAndQuit | Quits Matchmaker | Returns to TUI | Returns to TUI |
Become | Replaces process | Replaces process | Replaces process |
BecomeOrConfirm | Quits Matchmaker | Displays confirmation prompt | Resumes Matchmaker (on Ctrl+C or code 100) |
BecomeOrResume | Quits Matchmaker | Resumes Matchmaker | Quits with error (on crash/abnormal exit) |
NOTE
Custom helper scripts invoked via BecomeOrConfirm can exit with code 100 to instruct Matchmaker to resume the interactive picker without relying on user interrupts.