Reference

CLI reference

Every command, target, and image option.

Eight commands: five standalone, plus the service and its client. The standalone commands each open a display, do their work, and exit.

Command	Purpose
capture	Capture a desktop, region, or window and return it.eensh capture [TARGET] [IMAGE] [OUTPUT]
diff	Compare two saved images and report what changed.eensh diff BEFORE AFTER [OPTIONS]
wait-change	Block until the visible state departs from a baseline.eensh wait-change [TARGET] [OPTIONS]
wait-stable	Block until the visible state stops moving.eensh wait-stable [TARGET] [OPTIONS]
observe	Wait for a transition, then for it to settle, and return the result.eensh observe [TARGET] [OPTIONS]
serve	Run the persistent capture service in the foreground.eensh serve [--socket PATH]
ping	Ask a running service whether it is alive.eensh ping [--socket PATH] [--json]
session	Talk to a running service: create, capture, diff, observe, realtime.eensh session <SUBCOMMAND>

Target options

Shared by every command that captures. All three are optional.

Option	Meaning
--display DISPLAY	X11 display, for example `:1`. Overrides `$DISPLAY`.
--region X,Y,W,H	A rectangle in source-desktop pixels. Never clipped silently.
--window ID	An X11 window by ID, decimal or `0x`-prefixed. Reads the visible desktop under it.

Image options

Option	Meaning
--format png\|jpeg	Output format. Defaults to `png`, or is inferred from the output file extension.
--quality N	JPEG quality, 1–100. Default `80`. JPEG only.
--compression fast\|default\|best	PNG effort. Default `default`, which maps to the encoder's Balanced level — see the performance page before using it on a large screen.
--width N	Resize to a width, preserving aspect ratio. Applied before encoding.
--height N	Resize to a height, preserving aspect ratio.
--scale F	Resize by a uniform factor.

Output options

Option	Meaning
OUTPUT	Positional output path. `-` or omitted means stdout.
--base64	Embed the encoded image in the JSON response. Requires `--json`.
--json	Emit the structured JSON response.
--time	Print per-stage timings to stderr.

bash

$ eensh capture shot.png                    # PNG to a file
eensh capture --format jpeg shot.jpg      # JPEG to a file
eensh capture --format png - | consumer   # PNG on stdout
eensh capture --base64 --json             # agent-facing JSON on stdout

Observation options

For wait-change, wait-stable, and observe.

Option	Meaning
--mode exact\|rgb	Comparison mode for change detection. Default `rgb`.
--pixel-threshold N	Largest per-channel difference treated as unchanged. Default `12`.
--area-threshold F	Smallest changed fraction treated as meaningful. Default `0.005`.
--interval D	Target cadence between samples. Default `100ms`.
--timeout D	Total deadline. Default `5s`. A timeout exits `100`, which is not an error.
--stable-for D	How long the scene must hold still. Default `300ms`.

Real-time options

Option	Default	Meaning
--frames	3	How many frames, 1–8. A maximum, not a promise.
--interval	50ms	Nominal spacing between sample opportunities.
--timeout	500ms	Deadline for starting a capture. Deliberately shorter than the observation default, because a real-time request is bounded by intent.

Presentation flags

Available on capture, latest, frame, diff, and realtime. With none of them supplied, the output is exactly what it was before presentation existed.

Option	Meaning
--overview-width W	Whole-frame overview width, preserving aspect ratio.
--overview-format png\|jpeg	Overview format.
--overview-quality N	Overview JPEG quality, 1–100.
--no-overview	Omit the whole-frame view, sending only regions.
--metadata-only	Describe every view and embed no pixels anywhere.
--region NAME=X,Y,W,H	A named source-space region, repeatable. Optional `@SCOPE` and `@!PRIORITY` suffixes.
--region-width W	Width for regions that do not name their own.
--region-format png\|jpeg	Format for regions that do not name their own.
--temporal MODE	`all-same`, `newest-detailed`, `newest-only`, or `metadata-older`.
--older-width W	Width for the older frames of a real-time stack.
--newest-width W	Width for the newest frame of a real-time stack.
--max-base64-bytes BYTES	Most base64 bytes the visual payload may occupy. Fitting is opt-in.
--changed-region	Crop to the Phase 2 changed region, for `session diff`.
--changed-padding PIXELS	Padding around the changed region, clamped at the source edges. Default `0`.

Session subcommands

Subcommand	Notes
session create	Resolves geometry eagerly, so a bad display fails here rather than on the first capture.
session list / info	Registry contents and one session’s state.
session capture	New frame, new ID, appended to history.
session latest / frame	Retrieval without touching the display.
session diff	Compares two retained frames.
session wait-change / wait-stable / observe	The same state machines, running through a session.
session realtime	A bounded temporal stack.
session close	Refused during an observation, with the session intact.

Global flags

Flag	Meaning
--socket	Service socket path. Defaults to `$EENSH_SOCKET`, then `$XDG_RUNTIME_DIR/eensh.sock`, then a user-scoped temporary path.
--json	Emit the structured response. Required on every session command, because those responses are the result.

Every flag above has a corresponding typed field on the Rust client — see the client page.