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

# Commands

## Observe

```sh
deskctl doctor
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. `snapshot` produces a
screenshot plus window refs. `list-windows` is the same window tree without the
side effect of writing a screenshot.

## Wait

```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 a window

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

## Input and mouse

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

## Launch

```sh
deskctl launch firefox
deskctl launch code -- --new-window
```

## Selectors

Prefer explicit selectors when the target matters:

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