Skip to main content
Focus a window, launch an installed app, or open a file with the app that owns it. Start the display first. CLI and cURL examples use $RT with the display already started (Screen).

Focus a window

windows returns {windows: [...], focused} — focused is the focused window’s id; each entry carries id, geometry (x, y, w, h), title, window_class, instance, desktop (virtual-desktop index), focused, and states (window-manager flags). window_class filters by class substring. window_op takes the window id and an op — focus, close, raise, lower, move (with x/y), resize (with w/h), maximize, unmaximize, minimize, fullscreen, unfullscreen — and returns the window’s post-op record.
Window ops need a window manager — pass wm at enable (or run a desktop template, which ships one). Without a WM, windows lists what the X server maps but placement ops have no effect.

Launch an app

apps lists the applications the template registered — each entry is {id, name, exec, icon, categories} (a freedesktop entry). launch_app starts one by its apps() id; uri substitutes into the app’s exec line (open a URL in the registered browser, a file in the editor, …). wait_window blocks until a new top-level window maps — the launch-then-act pattern — and returns {pid, window_id, app}; timeout_ms caps the wait (default 10000 when waiting).

Open a file

open hands a file path or URL to its registered handler — a URL to the default browser, a PDF to the document viewer, a text file to the editor — and returns {pid, window_id, app, mime} (mime names the detected type, window_id is set when wait_window resolved one). Use it when you want the platform’s routing rather than picking the app yourself.

Use the window that opened

  • A wait_window launch or open is how you chain into input: the returned window_id is the new top-level window, ready for window_op or a screenshot cropped to its geometry.
  • apps reflects the template — a template without registered desktop entries returns an empty list, and launch_app then returns 404 for unknown ids.
  • For web work prefer browser.open — it manages the browser’s lifecycle, tabs, and headless mode. open/launch_app are for everything else.

Endpoints