Skip to content
Menu

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, or nil, stderr when the command failed.

  • wm.query(kind) returns a Lua table. The kinds are windows, focused, workspaces, monitors and monitor (the focused monitor). A monitor has id, name, index (1 is the leftmost), role (main, secondary, tertiary), main, workspace, special, focused, frame and work_area. wm list monitors shows the same, and wm list monitors --focused only the monitor that has the focus (add --json for scripts). The monitor_changed event has the monitor id, its name and its workspace, 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_changed and config_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). $HOME and $(...) work. A folder such as /Applications/Foo.app is not a command: use open -a Foo, or the program inside it (/Applications/Foo.app/Contents/MacOS/foo). A command that cannot start is in wm logs (source exec).

    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 string

    To give the new window options (a workspace, a size, floating), use the exec command of wm through wm.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 the wm.rule rules.

    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"), and wm.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.rule and wm.workspace work only while the config file loads (not inside a bind or an event handler). wm.dispatch, wm.exec, wm.press, wm.query, wm.log and wm.on work 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.log writes to wm logs, a script that fails too (source lua).

  • The config folder is on Lua’s package.path, so a long config can be split in files: require("hyper") loads hyper.lua that sits next to init.lua. A change to init.lua reloads the config; after a change in a module, run wm 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.