deskctl runtime contract

All commands support --json and use the same top-level envelope:

{
  "success": true,
  "data": {},
  "error": null
}

Use --json whenever you need to parse output programmatically.

Stable window fields

Whenever a response includes a window payload, these fields are stable:

ref_id
window_id
title
app_name
x
y
width
height
focused
minimized

Use window_id for stable targeting inside a live daemon session. Use ref_id or @wN for short-lived follow-up actions after snapshot or list-windows.

Stable grouped reads

deskctl get active-window -> data.window
deskctl get monitors -> data.count, data.monitors
deskctl get version -> data.version, data.backend
deskctl get systeminfo -> runtime-scoped diagnostic fields such as backend, display, session_type, session, socket_path, screen, monitor_count, and monitors

Stable waits

deskctl wait window -> data.wait, data.selector, data.elapsed_ms, data.window
deskctl wait focus -> data.wait, data.selector, data.elapsed_ms, data.window

Stable structured error kinds

When a command fails with structured JSON data, these kind values are stable:

selector_not_found
selector_ambiguous
selector_invalid
timeout
not_found

Wait failures may also include window_not_focused in the last observation payload.

Best-effort fields

Treat these as useful but non-contractual:

exact monitor names
incidental text formatting in non-JSON mode
default screenshot file names when no explicit path was provided
environment-dependent ordering details from the window manager

1.7 KiB Raw Permalink Blame History