Skip to main content
visor returns a structured JSON envelope for normal commands. If you run visor --help or invoke the CLI with no command, the CLI prints a plain-text usage summary instead.

​
Top-level envelope

FieldTypeMeaning
statusstringok or fail
command_idstringUnique command invocation id
started_atstringUTC timestamp
ended_atstringUTC timestamp
artifactsarray of stringArtifact paths associated with the response
next_actionstringHint for the next logical operation
errorobjectPresent only on failure
dataobjectCommand-specific payload

​
Error payload

FieldTypeMeaning
codestringStructured error code
messagestringHuman-readable summary
likely_causestringBest current explanation
next_stepstringSuggested remediation

​
Run result

When a scenario run succeeds or fails, data.run contains a run result.
FieldTypeMeaning
run_idstringUnique run id
platformstringandroid or ios
devicestringResolved device name
started_atstringRun start timestamp
ended_atstringRun end timestamp
statusstringok or fail
stepsarrayOrdered step results
assertionsarrayAssertion results
artifactsarray of stringFinal copied artifact paths
determinism_signaturestringSHA-256 signature of normalized run data
seednumberPresent when the scenario provides a seed
errorobjectPresent when the run failed

​
Step result

FieldTypeMeaning
idstringStep id
commandstringExecuted command
statusstringok or fail
duration_msnumberStep duration
detailsobjectAdapter-returned payload
errorobjectPresent when the step failed

​
Assertion result

Assertion results are plain objects with these fields:
FieldTypeMeaning
idstringAssertion id
typestringAssertion type
targetstringSelector that was checked
statusstringpassed or failed
detailsstringFailure or informational detail

​
Benchmark result payload

Benchmark responses store their command-specific payload in data.
FieldTypeMeaning
runsnumberNumber of iterations attempted
thresholdnumberRequired determinism threshold
determinismScorenumberCalculated score
passbooleanWhether the benchmark passed
failuresnumberCount of failed iterations
runIdsarray of stringRun ids created during the benchmark
warningsarrayValidation warnings carried through from scenario parsing

​
Validation payload

Validation responses use this data structure:
FieldTypeMeaning
validbooleanWhether the scenario passed validation
issuesarrayValidation errors and warnings
Important behavior:
  • schema-invalid scenarios return status: "ok" with data.valid: false and a non-zero process exit code
  • malformed JSON or unreadable files return a failure envelope with status: "fail"
Each issue contains:
  • severity
  • code
  • message
  • path

​
Example envelope

{
  "status": "ok",
  "command_id": "cmd_123456789abc",
  "started_at": "2026-03-29T16:00:00Z",
  "ended_at": "2026-03-29T16:00:01Z",
  "artifacts": [
    "artifacts/run_123/screenshots/001-app-opened.png"
  ],
  "next_action": "report",
  "data": {
    "run": {
      "run_id": "run_123456789abc",
      "platform": "android",
      "device": "emulator-5554",
      "started_at": "2026-03-29T16:00:00Z",
      "ended_at": "2026-03-29T16:00:01Z",
      "status": "ok",
      "steps": [],
      "assertions": [],
      "artifacts": [],
      "determinism_signature": "...",
      "seed": 42
    },
    "warnings": []
  }
}