Reference
Lua API
wm.config, wm.bind, wm.on, wm.dispatch, wm.query and the rest, with editor support.
wm.config, wm.bind, wm.remap, wm.mode, wm.gesture, wm.rule, wm.workspace, wm.on, wm.dispatch, wm.query,
wm.exec, wm.press, wm.log and wm.version.
-
wm.dispatch(command [, { window = id or selector }])runs a command. It returns stdout, ornil, stderrwhen the command failed. -
wm.query(kind)returns a Lua table. The kinds arewindows,focused,workspaces,monitorsandmonitor(the focused monitor). A monitor hasid,name,index(1 is the leftmost),role(main,secondary,tertiary),main,workspace,special,focused,frameandwork_area.wm list monitorsshows the same, andwm list monitors --focusedonly the monitor that has the focus (add--jsonfor scripts). Themonitor_changedevent has themonitorid, itsnameand itsworkspace, so a config can react to the monitor in use:wm.on("monitor_changed", function(e) if e.name:find("LG") then wm.dispatch("layout set scrolling") else wm.dispatch("layout set tiling") end end) local here = wm.query("monitor") -- the focused monitor: here.name, here.index, here.role -
Events:
window_open,window_close,window_focus,window_title,window_floating,window_fullscreen,window_moved,workspace_changed,special_changed,monitor_changed,layout_changed,mode_changedandconfig_reloaded.wm.on(event, [filter,] handler)takes an optional table of fields that must match. -
wm.exec(command)runs a shell command and returns nothing. It does not wait for the command and it drops its output. wm runs it as/bin/zsh -c "<command>", which does not read.zshrc: use absolute paths (/opt/homebrew/bin/htop).$HOMEand$(...)work. A folder such as/Applications/Foo.appis not a command: useopen -a Foo, or the program inside it (/Applications/Foo.app/Contents/MacOS/foo). A command that cannot start is inwm logs(sourceexec).wm.bind("alt-t", function() wm.exec("open -a Terminal") end) wm.bind("alt-shift-t", "exec open -a Terminal") -- the same, as a command stringTo give the new window options (a workspace, a size, floating), use the
execcommand of wm throughwm.dispatch. The options are--float,--tile,--center,--maximize,--no-focus,--workspace <n>,--monitor <m>,--width <fraction>,--size <w>,<h>and--layout <name>, and they go before--. They add to thewm.rulerules.wm.dispatch("exec --float --center --size 0.5,0.5 -- /Applications/kitty.app/Contents/MacOS/kitty -e htop") -
wm.press(key)types a key now ("play","cmd-shift-4"), andwm.remap(chord, key)makes a chord type another key. See The hyper key, remaps and typing keys. -
wm.config,wm.bind,wm.remap,wm.mode,wm.gesture,wm.ruleandwm.workspacework only while the config file loads (not inside a bind or an event handler).wm.dispatch,wm.exec,wm.press,wm.query,wm.logandwm.onwork everywhere. A function bind or handler runs on its own thread, so a slow one never blocks the keyboard; one that runs longer than 2 seconds is stopped.wm.logwrites towm logs, a script that fails too (sourcelua). -
The config folder is on Lua’s
package.path, so a long config can be split in files:require("hyper")loadshyper.luathat sits next toinit.lua. A change toinit.luareloads the config; after a change in a module, runwm daemon reload.
Editor support
init.lua gets completion, hover help and warnings in any editor that runs
lua-language-server (LuaLS): VS Code with the Lua extension, Neovim with lua_ls, Helix, Zed
and others. The server reads the type stubs in types/wm.lua. They describe the whole API: config keys with defaults and
ranges, enum values, command strings, bind options, rule fields, event fields and the tables that wm.query returns.
wm never loads this file. It exists for the editor.
build-app.sh puts the stubs inside the app, so you do not need this repository to use them. One command sets
everything up:
wm lsp # shows the folder of the stubs and the .luarc.json that LuaLS needs
wm lsp --write # saves it next to your config, as ~/.config/wm/.luarc.json
--write stops if a .luarc.json is already there. Use --force to replace it, or add the printed folder to the
workspace.library list of your file by hand. This is what the file looks like:
{
"diagnostics.neededFileStatus": { "missing-fields": "Any", "undefined-field": "Any" },
"runtime.version": "Lua 5.4",
"workspace.library": ["/Applications/wm.app/Contents/Resources/types"]
}
Open init.lua and the editor does the rest. LuaLS finds the file because it sits in the folder of init.lua. If you
move wm.app, run wm lsp --write --force again, because the path of the stubs changes. If you work on wm itself, you
can point workspace.library at the types folder of the repository instead.
Some examples of what you get: completion for wm.config { ... } keys and values (layout = " offers scrolling and
tiling), the command strings of wm.bind, the fields of wm.rule, the event names of wm.on with the fields of each
event, and a warning for a wrong value (layout = "grid") or a wrong event name. LuaLS does not warn about an unknown key
inside a table (gaps = { outr = 1 }). wm still rejects it when the config loads.
A test keeps the stubs in step with the API: it fails when a wm function or a top-level config key has no stub.