Commands

The public CLI is intentionally small. Most workflows boil down to grouped reads, grouped waits, selector-driven actions, and a few input primitives.

Observe and inspect

deskctl doctor
deskctl upgrade
deskctl snapshot
deskctl snapshot --annotate
deskctl list-windows
deskctl screenshot
deskctl screenshot /tmp/screen.png
deskctl get active-window
deskctl get monitors
deskctl get version
deskctl get systeminfo
deskctl get-screen-size
deskctl get-mouse-position

doctor checks the runtime before daemon startup. upgrade checks for a newer published version, shows a short confirmation prompt when an update is available, and supports --yes for non-interactive use. snapshot produces a screenshot plus window refs. list-windows is the same window tree without the side effect of writing a screenshot. The grouped get commands are the preferred read surface for focused state queries.

Wait for state transitions

deskctl wait window --selector 'title=Chromium' --timeout 10
deskctl wait focus --selector 'id=win3' --timeout 5
deskctl --json wait window --selector 'class=chromium' --poll-ms 100

Wait commands return the matched window payload on success. In --json mode, timeouts and selector failures expose structured kind values.

Act on windows

deskctl launch chromium
deskctl focus @w1
deskctl focus 'title=Chromium'
deskctl click @w1
deskctl click 960,540
deskctl dblclick @w2
deskctl close @w3
deskctl move-window @w1 100 120
deskctl resize-window @w1 1280 720

Selector-driven actions accept refs, explicit selector modes, or absolute coordinates where appropriate.

Keyboard and mouse input

deskctl type "hello world"
deskctl press enter
deskctl hotkey ctrl shift t
deskctl mouse move 100 200
deskctl mouse scroll 3
deskctl mouse scroll 3 --axis horizontal
deskctl mouse drag 100 200 500 600

Supported key names include enter, tab, escape, backspace, delete, space, arrow keys, paging keys, f1 through f12, and any single character.

Selectors

Prefer explicit selectors when the target matters. They are clearer in logs, more deterministic for automation, and easier to retry safely.

ref=w1
id=win1
title=Chromium
class=chromium
focused

Legacy shorthand is still supported:

@w1
w1
win1

Bare strings like chromium are fuzzy matches. They resolve when there is one match and fail with candidate windows when there are multiple matches.

Global options

Flag	Env	Description
`--json`		Output as JSON
`--socket <path>`	`DESKCTL_SOCKET`	Path to daemon Unix socket
`--session <name>`		Session name for multiple daemons (default: `default`)

deskctl manages the daemon automatically. Most users never need to think about it beyond --session and --socket.