Command reference

Documentation Index

Fetch the complete documentation index at: https://visorai.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

This page documents the current command surface exactly as implemented. If you run visor --help, visor -h, or invoke the CLI with no command, visor prints a usage summary instead of a JSON response envelope. visor --version and visor -v print the package version instead of a JSON response envelope.

​

Global runtime inputs

These inputs are accepted globally and, where relevant, by individual commands. Important notes:

• format is currently informational only for normal commands; the implementation still returns JSON envelopes
• visor --help, visor -h, and no-command invocation print plain-text usage instead of JSON
• visor --version and visor -v print the package version instead of JSON
• platform is inferred from the selected device; --platform is not accepted

​

Direct action commands

​

tap

Purpose: click an element or coordinate. Inputs:

• target mode: target
• coordinate mode: x, y
• optional: normalized

Returns action payload fields:

• action
• platform
• args

args contains either:

• target, or
• x, y, and normalized

​

navigate

Purpose: move to a destination. Required input:

• to

Returns action payload fields:

• action
• platform
• args.to

Current behavior:

• the destination is passed to WebdriverIO through url(to)

​

act

Purpose: perform a helper action. Supported variants:

• name=type with target and value
• name=back

Returns action payload fields:

• action
• platform
• args

​

scroll

Purpose: perform a page-style vertical scroll. Required input:

• direction with value up or down

Optional input:

• percent, default 70

Returns action payload fields:

• action
• platform
• args.direction
• args.percent

Current behavior:

• Android uses Appium scroll gestures within the current viewport
• iOS attempts the same gesture path and falls back to a touch swipe when needed

​

screenshot

Purpose: capture a PNG image. Optional input:

• label

Returns action payload fields:

• action
• platform
• args.label
• args.file
• args.path
• args.width
• args.height

If label is omitted, the runtime defaults it to capture.

​

wait

Purpose: pause execution. Required input:

• ms

Returns action payload fields:

• action
• platform
• args.ms

​

source

Purpose: capture current UI source as XML. Optional inputs:

• label
• path

Returns action payload fields:

• action
• platform
• args.label
• args.file
• args.path
• args.format
• args.bytes

For direct action commands, run visor start first.

​

Scenario commands

​

validate

Purpose: parse a scenario and return validation issues. Required input:

• scenario

Response data fields:

• valid
• issues

Exit behavior:

• returns success when the scenario is valid
• returns a non-zero exit code with status: ok when the scenario is syntactically valid JSON but fails schema validation
• returns a failure envelope when parsing fails or the file cannot be read

​

run

Purpose: execute one scenario, evaluate assertions, and write reports. Required input:

• scenario

Optional runtime inputs:

• device
• timeout
• output
• server-url
• app-id
• attach

Response data fields:

• run
• warnings

The run object contains the full run result, including step results, assertion results, artifacts, determinism signature, and run-level error data. For scenario runs, run visor start first.

​

benchmark

Purpose: run one scenario repeatedly and compute a determinism score. Required input:

• scenario

Optional inputs:

• runs with default 20
• threshold with default 95.0
• the same runtime inputs accepted by run

Response data fields:

• runs
• threshold
• determinismScore
• pass
• failures
• runIds
• warnings

For benchmark runs, run visor start first.

​

report

Purpose: return guidance about where run reports are stored. Optional input:

• path, which defaults to artifacts

Response data fields:

• message
• path
• format

​

Runtime lifecycle commands

​

start

Purpose: start the Visor daemon and ensure Appium is reachable. Optional inputs:

• server-url
• appium-cmd

Response data fields:

• serverUrl
• daemon
• appium

​

status

Purpose: report Visor daemon state, Appium reachability, and warm sessions. Optional inputs:

• server-url

Response data fields:

• serverUrl
• daemon
• appium

​

stop

Purpose: close warm sessions and stop the Visor daemon. Optional inputs:

• server-url
• force

Response data fields:

• serverUrl
• stopped
• daemon
• appium

​

Response envelope behavior

Every command returns the same top-level envelope fields:

• status
• command_id
• started_at
• ended_at
• artifacts
• next_action
• error
• data

next_action is a hint, not an execution chain. Examples include run, report, and none. Help and version output are the exceptions: visor --help, visor -h, and no-command invocation print usage text instead of an envelope, while visor --version and visor -v print the package version.