mirror of
https://github.com/harivansh-afk/deskctl.git
synced 2026-04-15 17:00:59 +00:00
114 lines
3.1 KiB
Text
114 lines
3.1 KiB
Text
---
|
|
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`.
|