Commands

All commands follow the JSON-RPC 2.0 request/response format described in the Introduction. The examples below use $SOCK as a shorthand for the socket path:

SOCK="$HOME/Library/Application Support/app.torchsnap/control.sock"

show

Make the launcher window visible. Positions it on the monitor under the cursor, matching the behavior of the global keyboard shortcut.

Parameters: none

echo '{"jsonrpc":"2.0","id":1,"method":"show"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"ok": true}}

hide

Hide the launcher window without resetting state. The search query, selection, and any active gadget view are preserved. Note that the normal focus-loss behavior may still clear state independently; use dismiss when you want an explicit reset.

Parameters: none

echo '{"jsonrpc":"2.0","id":1,"method":"hide"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"ok": true}}

toggle

Toggle the launcher’s visibility. If hidden, shows it. If visible, dismisses it, clearing the query and selection, just like pressing Escape. This matches the behavior of the global keyboard shortcut.

Parameters: none

echo '{"jsonrpc":"2.0","id":1,"method":"toggle"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"ok": true}}

dismiss

Hide the launcher and explicitly reset its state: clears the search query, selection, and any active gadget view. This matches the behavior of pressing Escape in the launcher. Prefer dismiss over hide when the intent is to close the launcher cleanly.

Parameters: none

echo '{"jsonrpc":"2.0","id":1,"method":"dismiss"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"ok": true}}

If the launcher’s frontend is not connected, dismiss returns error code -1 with the message launcher frontend is not connected and leaves the launcher as it is. Use hide to hide it anyway.

query

Set the search input text. The launcher’s search pipeline runs automatically after the text is set, just as if the user had typed it. If the launcher is not visible, the query is set but no results are shown until show or toggle is called.

Parameters:

Name	Type	Required	Description
text	string	yes	The search query text.

echo '{"jsonrpc":"2.0","id":1,"method":"query","params":{"text":"firefox"}}' \
  | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"ok": true}}

Returns error code -1 if the text parameter is missing, and also when the launcher’s frontend is not connected yet or its page is gone (message launcher frontend is not connected). A successful answer means Torchsnap handed the text to the launcher’s page. While that page reloads, the text can still get lost; snapshot shows whether it arrived.

status

Report the current launcher state.

Parameters: none

Field	Type	Description
visible	boolean	Whether the launcher window is currently visible.
focused	boolean	Whether the launcher window has keyboard focus. Some desktops, such as GNOME on Wayland, can refuse focus to a window that just appeared, so read it a moment after show.
ready	boolean	Whether the launcher has reported its layout and its frontend is connected. Until then show fails, and query and dismiss return error code -1.
targetMonitor	object or null	The monitor Torchsnap last placed the launcher on, or null before the first placement. See Target monitor.

A script that starts Torchsnap can wait until ready is true before it sends show or query:

echo '{"jsonrpc":"2.0","id":1,"method":"status"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"visible": false, "focused": false, "ready": true, "targetMonitor": {"name": "Built-in Retina Display", "x": 0.0, "y": 0.0, "width": 1512.0, "height": 982.0, "scaleFactor": 2.0}}}

ready reflects what Torchsnap’s backend knows. It stays true while the launcher’s page reloads, until the new page connects, and it turns true one render before the launcher shows its real content. When a script needs the launcher to have applied a command, it checks with snapshot.

Target monitor

targetMonitor tells you where Torchsnap aimed the launcher: the monitor under the mouse pointer, or the primary monitor when no monitor contains it.

Field	Type	Description
name	string or null	The monitor’s name as the windowing toolkit reports it.
x, y	number	The monitor’s top-left corner in logical units.
width, height	number	The monitor’s size in logical units.
scaleFactor	number	The monitor’s scale factor as the windowing toolkit reports it.

On Linux the name is the monitor’s model string, which can be missing or the same for two identical monitors, and the scale factor is a whole number rather than a fractional desktop scale. Match monitors by their rectangle, not by name.

Wayland

On Wayland Torchsnap does not learn where the mouse pointer is, so the target is the monitor at (0,0), or the primary one, and the compositor decides where the window really appears.

windows

List Torchsnap’s open windows: the launcher, labelled main, and whichever of the settings, developer tools, update and welcome windows are open. Those four exist only while they are open; the launcher always exists.

Parameters: none

The result holds a windows array, sorted by label, with one entry per window:

Field	Type	Description
label	string	The window’s label: main, settings, devtools, update or welcome.
title	string	The window title, empty for the launcher.
visible	boolean	Whether the window is visible.
focused	boolean	Whether the window has keyboard focus.

With the settings window open and the launcher hidden:

echo '{"jsonrpc":"2.0","id":1,"method":"windows"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {"windows": [
  {"label": "main", "title": "", "visible": false, "focused": false},
  {"label": "settings", "title": "Torchsnap Settings", "visible": true, "focused": true}
]}}

info

Identify the running Torchsnap: its process, build, folders, tray icon and, on Linux, the display it is connected to. When you run two instances side by side, each with its own data folder, these values tell them apart.

Parameters: none

Field	Type	Description
pid	number	The process id.
version	string	The app version.
gitHash	string	The short git hash the app was built from.
dataDir	string	The app data folder.
socketPath	string	The control socket’s path, inside the data folder.
trayId	string	The tray icon’s id, <pid>-1. On Linux the tray’s AppIndicator is named tray-icon tray app <trayId>.
display	object or null	On Linux, the display Torchsnap’s windows are on: backend (wayland or x11) and name, such as wayland-0 or :0. null on other platforms.

On a Raspberry Pi running GNOME on Wayland:

echo '{"jsonrpc":"2.0","id":1,"method":"info"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {
  "pid": 4242, "version": "0.15.0", "gitHash": "1d9cc637",
  "dataDir": "/home/pi/.local/share/app.torchsnap",
  "socketPath": "/home/pi/.local/share/app.torchsnap/control.sock",
  "trayId": "4242-1",
  "display": {"backend": "wayland", "name": "wayland-0"}
}}

snapshot

Report what the launcher shows: the query, the results, the selection, the gadget views, whether its content is visible and whether the search input is the active element. Unlike status, Torchsnap asks the launcher’s frontend for these, so the answer can take up to two seconds.

Parameters: none

Field	Type	Description
query	string	Text in the search input. A gadget can change it without a new search, so it can differ from the text the results belong to.
searching	boolean	The last search started has not finished.
results	array	The result list on screen, in display order, each with source, id, title and subtitle (string or null). Empty while a gadget view replaces the list.
selectedIndex	number or null	Index into results; null when no list is shown, the inline view holds the selection, or nothing is selected.
inlineView	object or null	The inline gadget view above the list, with gadgetId and view.
inlineViewSelected	boolean	The inline view holds the selection.
gadgetView	object or null	The gadget view that replaces the list, with gadgetId and view.
contentVisible	boolean	The launcher’s content is not blanked. On Linux the launcher blanks it while hiding and shows it again after showing; on other platforms it is always true.
inputFocused	boolean	The search input is the page’s active element. It stays true while the window is hidden or unfocused, so read it together with visible and focused from status.

After searching for “fire” with Firefox installed:

echo '{"jsonrpc":"2.0","id":1,"method":"snapshot"}' | socat - UNIX-CONNECT:"$SOCK"

Response

{"jsonrpc": "2.0", "id": 1, "result": {
  "query": "fire", "searching": false,
  "results": [
    {"source": "app-launcher", "id": "/Applications/Firefox.app", "title": "Firefox", "subtitle": "/Applications/Firefox.app"}
  ],
  "selectedIndex": 0,
  "inlineView": null, "inlineViewSelected": false, "gadgetView": null,
  "contentVisible": true, "inputFocused": true
}}

The answer comes from the launcher’s last render, except contentVisible and inputFocused, which Torchsnap reads from the page when the request arrives. Right after query, searching can still be true, or the results can still belong to the previous text, so poll until searching is false and query matches what you sent. snapshot returns error code -1 when the launcher’s frontend is not connected, -4 when it does not answer within two seconds or its page reloads first, and -3 when its answer is malformed.

Error codes

Protocol errors

Returned by the JSON-RPC framing layer before any command handler runs.

Code	Meaning
-32700	Parse error: the request is not valid JSON.
-32600	Invalid request: missing method field, malformed envelope, or a request line longer than 1 MiB.
-32601	Method not found: no handler registered for the given method name.

Example

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found: foo"}}

Application errors

Returned by individual command handlers.

Code	Meaning
-1	Invalid state: a precondition is not met (for example, the launcher’s frontend is not connected) or a required parameter is missing.
-3	Internal error: an unexpected failure in the handler, or a malformed answer from the launcher’s frontend.
-4	Unanswered: the launcher’s frontend did not answer in time, or its page reloaded before it did. A retry can succeed.

Scripting examples

Show, search, then dismiss

{
  echo '{"jsonrpc":"2.0","id":1,"method":"show"}'
  sleep 0.5
  echo '{"jsonrpc":"2.0","id":2,"method":"query","params":{"text":"calculator"}}'
  sleep 2
  echo '{"jsonrpc":"2.0","id":3,"method":"dismiss"}'
} | socat - UNIX-CONNECT:"$SOCK"

Check if the launcher is visible

VISIBLE=$(echo '{"jsonrpc":"2.0","id":1,"method":"status"}' \
  | socat - UNIX-CONNECT:"$SOCK" \
  | jq -r '.result.visible')

if [ "$VISIBLE" = "true" ]; then
  echo "Launcher is visible"
else
  echo "Launcher is hidden"
fi