hs.ipc
ModuleModule for enabling CLI access to Hammerspoon 2 via the hs command-line tool.
The IPC server must be explicitly started from your configuration — it does not run by default.
Once started, the hs command-line tool connects via XPC and evaluates JavaScript
interactively, with optional live log streaming.
Communication is secured with a same-team code-signing requirement in release builds, so only binaries signed with the same Team ID can connect.
Quick start
// In your Hammerspoon 2 config (init.js):
hs.ipc.start()
Install the CLI tool once:
hs.ipc.installBinary() // symlinks hs to /usr/local/bin/hs
Then in a terminal:
hs
hs> hs.reload()
undefined
hs> 2 + 2
4
Run with live log output:
hs --log-level info
Properties
Methods
hs.ipc.start() -> None
Start the IPC server.
The server listens on a named XPC Mach service (`net.tenshu.Hammerspoon-2.ipc`).
In release builds, only processes signed with the same Team ID can connect.
Calling `start()` when already running logs a warning and does nothing.
Declaration
hs.ipc.start() -> NoneReturns
None
Example
hs.ipc.start()hs.ipc.stop() -> None
Stop the IPC server and disconnect all connected clients.
Declaration
hs.ipc.stop() -> NoneReturns
None
Example
hs.ipc.stop()hs.ipc.installBinary(directory) -> boolean
Install the `hs` command-line tool to the given directory as a symlink.
Creates a symlink in the target directory that points to the `hs` binary inside the
Hammerspoon 2 app bundle. Using a symlink means the CLI automatically reflects any
app update without reinstalling. Any existing `hs` file at that path is replaced.
The directory must be on your `$PATH` for `hs` to work without a full path.
**Permissions:** `/usr/local/bin` is typically user-writable on Intel Macs with Homebrew.
On Apple Silicon, prefer `/opt/homebrew/bin`. On a stock Mac (no Homebrew), both
directories require root — if this method returns `false`, run the logged command in
a terminal with `sudo`.
Declaration
hs.ipc.installBinary(directory) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| directory | JSValue | Directory to install into. Defaults to `/usr/local/bin`. |
Returns
boolean
`true` on success, `false` on error (details logged to the console).
Example
hs.ipc.installBinary() // install to /usr/local/bin/hs
hs.ipc.installBinary("/opt/homebrew/bin") // install to /opt/homebrew/bin/hshs.ipc.uninstallBinary(directory) -> boolean
Remove the `hs` command-line tool from the given directory.
Declaration
hs.ipc.uninstallBinary(directory) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| directory | JSValue | Directory to remove from. Defaults to `/usr/local/bin`. |
Returns
boolean
`true` on success, `false` if not found or on error.
Example
hs.ipc.uninstallBinary()
hs.ipc.uninstallBinary("/opt/homebrew/bin")hs.ipc.isBinaryInstalled(directory) -> boolean
Check whether the `hs` command-line tool exists at the given directory.
Declaration
hs.ipc.isBinaryInstalled(directory) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| directory | JSValue | Directory to check. Defaults to `/usr/local/bin`. |
Returns
boolean
`true` if an `hs` binary exists at that path.
Example
if (hs.ipc.isBinaryInstalled()) {
console.log("hs CLI is available")
}