Trigger a Hammerspoon Lua function from an external script or another app via the hs CLI and URL scheme
domain: hammerspoon.org · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Add require("hs.ipc") to init.lua so the IPC server used by both the CLI and the URL scheme is loaded whenever Hammerspoon starts
Install the command-line tool once from the Hammerspoon console with hs.ipc.cliInstall()
From a shell script, run arbitrary Lua in the running instance with hs -c 'hs.window.focusedWindow():centerOnScreen()'
Alternatively, register a handler with hs.urlevent.bind("myAction", function(eventName, params) ... end) and trigger it from any app via open "hammerspoon://myAction?foo=bar"
No manual reconnect handling is needed — the hs CLI automatically re-attaches after a config reload invalidates the previous IPC port
Known gotchas
The hs CLI silently fails to connect if hs.ipc was never required in init.lua — it is not loaded by default
hs.ipc.cliInstall() writes a symlink that needs write access to /usr/local/bin (or a given path); on modern macOS this can require sudo and a Full Disk Access grant for the invoking terminal
URL-scheme and CLI triggers run with whatever OS permissions Hammerspoon itself currently holds (Accessibility, Screen Recording, etc.) — a handler needing window control fails quietly if a permission was revoked after an OS update
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?