reference

Reference

Commands, flags, configuration and environment for Tendril 0.0.4.

Commands

Command	Main options	Does
`list`	`--all-apps` (Android)	Windows, displays, cameras and devices
`list-elements`	`--include-offscreen`	Semantic elements of a target, or globally
`capture`	`-o` `--format png\|jpeg` `--compression` `--max-width` `--max-height` `--timeout-ms`	A screenshot or camera frame
`run input`	`--restore-focus` `--no-restore-focus` `--no-lock` `--lock-timeout-ms` `--lock-stale-ms` `--lock-path`	Text or a run sequence
`listen`	`--output`	Record audio, or report capability
`clipboard get\|set`		Read, or own and serve, a text selection
`alias`	`--name` `--shell bash\|zsh\|fish\|powershell`	A shell function bound to a target
`permissions`	`--request` (macOS)	Permission status, read-only by default
`update`		Check, stage and promote a release
`version`		The running version
`mcp stdio`		The MCP server

Flags for every command

Flag	Means
`--json`	A JSON envelope instead of text
`--window ID`, `--display ID`, `--camera ID`	The target; acting commands need exactly one
`--remote user@host`	Run on another machine over SSH
`--wsl-tunnel`	Run the Windows build on the Windows host, from WSL
`--android SERIAL\|auto`	Drive an Android device over ADB

Configuration

Machine-local defaults live in ~/.config/tendril/config.yaml, or $TENDRIL_CONFIG_DIR/config.yaml. Flags override it.

capture:  format: png            # or jpeg  compression: 85        # 0–100  max_width: 512         # captures fit a 512 × 512 box unless raised  max_height: 512  timeout_ms: nulllogging:  level: info            # error, warn, info, debug or traceexecution_lock:  enabled: true  timeout_ms: 60000      # how long a run waits in the queue  stale_ms: 30000        # heartbeat age before a holder is reaped  path: null             # default: under the temporary directoryfeedback:                # optional; off when omitted  enabled: true  component: tendril  strategy:    type: webhook        # webhook, caco_cli, file, stderr or disabled    url: https://example.invalid/feedback    token_env: TENDRIL_FEEDBACK_TOKEN

Environment

Variable	Used for
`TENDRIL_CONFIG_DIR`	Where `config.yaml` is
`TENDRIL_LOCK_PATH`, `TENDRIL_LOCK_TIMEOUT_MS`, `TENDRIL_LOCK_STALE_MS`, `TENDRIL_NO_LOCK`	The execution lock
`TENDRIL_LOCK_SESSION`	The session part of the lock's name; otherwise from `WAYLAND_DISPLAY`, `DISPLAY` or `XDG_SESSION_ID`
`TENDRIL_REMOTE_BIN`	The tendril binary on a `--remote` host
`TENDRIL_WSL_WINDOWS_BIN`	The Windows binary for `--wsl-tunnel`
`TENDRIL_ANDROID_SERIAL`, `TENDRIL_ADB_BIN`, `TENDRIL_ANDROID_ARTIFACT_DIR`	The Android device, the adb binary and the debug trail
`TENDRIL_SKIP_PERMISSION_PROBE`	Skip the live macOS Screen Recording probe, for tests
`TENDRIL_*_FIXTURE_JSON`	Test fixtures for targets, captures, elements and input

Updates

tendril update uses the shared release flow: it discovers a newer tagged release, verifies its checksum, stages it and promotes it at the next start. tendril version prints the running version without touching anything.

Rust API

The workspace's Rust documentation is generated at publish time and served under api/: the tendril library and binary, the Windows backend crate and the shared command surface.

Development

Command	Does
`nix develop`	Rust, Clippy, rustfmt and helpers, pinned
`cargo test`	Unit tests and the integration suites (flows, MCP parity, platform contract, runtime-dependency audit)
`nix build .#checks.system.clippy`	The canonical Clippy gate
`scripts/tendril-headless.sh … smoke`	Smoke tests against a disposable desktop

This site is built from site/ by scripts/site/build.py and checked by scripts/check-site.py; scripts/build-docs.sh adds the Rust API and assembles what is published.