mirror of https://github.com/harivansh-afk/deskctl.git synced 2026-04-15 09:01:15 +00:00

* align docs and contract

* clean

* rename from deskctl-cli to deskctl

* runtime

2026-03-26 08:51:15 -04:00

1.7 KiB

Raw Blame History

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 Blame History