Skip to main content
visor returns a structured JSON envelope for normal commands. If you run visor --help, visor -h, or invoke the CLI with no command, the CLI prints a plain-text usage summary instead. If you run visor --version or visor -v, the CLI prints the package version 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
mapobjectPresent when mapped execution was considered for the run
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

​
Map metadata

Mapped execution metadata uses these fields:
FieldTypeMeaning
enabledbooleanWhether map reads and writes were enabled
usedbooleanWhether Visor used cached map knowledge for routing
updatedbooleanWhether the host app map changed during the command
repairedbooleanWhether Visor repaired a stale or missing route
repairsnumberCount of bounded repair passes used
schema_versionnumberApp-map schema version
pathstringHost path to the persisted app map when enabled
identitystringApp-map identity, scoped by platform and app id
summaryobjectPath-free app-map inventory attached to visor discover responses when the persisted map can be read
Direct action commands return this object in data.map. Scenario runs return it in data.run.map. A routed or repaired step may also include details.map.route, an ordered list of hidden route actions Visor performed before the requested step action. visor discover adds data.map.summary when mapped execution is enabled and the persisted map file is readable. The summary is safe to share in reviews because it does not include the host map path.
Summary fieldTypeMeaning
schema_versionnumberApp-map schema version read from disk
identitystringApp-map identity, scoped by platform and app id
app_idstringApp id used for the map
platformstringandroid or ios
screensnumberCount of discovered logical screens
variantsnumberCount of discovered screen variants
edgesnumberCount of recorded navigation edges
actionsnumberCount of stored action affordances
auth_required_variantsnumberCount of variants marked as requiring authentication
updated_atstringLast persisted map update timestamp

​
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": []
  }
}