---
layout: ../layouts/DocLayout.astro
title: Commands
toc: true
---

# 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

```sh
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

```sh
deskctl wait window --selector 'title=Firefox' --timeout 10
deskctl wait focus --selector 'id=win3' --timeout 5
deskctl --json wait window --selector 'class=firefox' --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

```sh
deskctl launch firefox
deskctl focus @w1
deskctl focus 'title=Firefox'
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

```sh
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.

```sh
ref=w1
id=win1
title=Firefox
class=firefox
focused
```

Legacy shorthand is still supported:

```sh
@w1
w1
win1
```

Bare strings like `firefox` 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`.