Skip to main content
Use this guide to install the TypeScript CLI, confirm it works, and then run a minimal scenario against a mobile runtime.

​
Requirements

Before you install visor, make sure you have:
  • Node.js 20 or later
  • npm
For mobile runs, you also need:
  • a bootable Appium environment for the selected device platform
  • a booted Android emulator or device, or an iOS simulator or device
  • the app identifier for the app you want visor to launch or attach to

​
Install visor

1

Install visor from npm

npm install -g visor-ai
2

Confirm the CLI is available

visor --help
This installs the visor CLI entry point and the runtime dependencies published with the visor-ai package.
3

Alternative: run from a source checkout

npm install
npm run build
node dist/main.js --help

​
Run your first command

Create a minimal scenario file named checkout-smoke.json: 
{
  "meta": {
    "name": "checkout-smoke",
    "version": "1"
  },
  "config": {
    "timeoutMs": 15000,
    "seed": 42,
    "artifactsDir": "./artifacts"
  },
  "steps": [
    {
      "id": "s1",
      "command": "screenshot",
      "args": {
        "label": "app-opened"
      }
    }
  ],
  "assertions": [],
  "output": {
    "report": ["summary", "json", "junit", "html"]
  }
}
Then validate it with: 
visor validate checkout-smoke.json
If you are running from a source checkout instead of a global install, replace visor with node dist/main.js. Expected result:
  • the top-level status is ok
  • data.valid is true
  • data.issues is an empty list
This verifies that your installation works and that visor can parse the scenario correctly. The output.report field in the example is accepted by the schema, but the current report writer always emits the standard report set regardless of that list.

​
Run the local development E2E harness

From a source checkout, you can run a deterministic scenario without a mobile device: 
npm run verify
For only the local E2E layer, run: 
npm run test:e2e:local
This uses visor run scenarios/local-fake-smoke.json --runtime local under the hood. It writes normal run reports and checks that expected report files, screenshots, and UI source artifacts exist.

​
Run your first scenario

Once validation passes, start the runtime daemon: 
visor start --server-url http://127.0.0.1:4723
Then execute the same scenario: 
visor run checkout-smoke.json --app-id com.example.app --output artifacts-test
visor writes a run directory under artifacts-test/<run-id>/ with files such as:
  • summary.txt
  • summary.json
  • junit.xml
  • timeline.log
  • report.html
  • copied artifacts under screenshots/ and sources/

​
Choose a target

When you need a specific app or device, add runtime inputs: 
visor run checkout-smoke.json \
  --device emulator-5554 \
  --app-id com.example.app
If you omit --device, visor detects running Android devices and booted iOS simulators. When more than one target is available, visor prompts you to choose one. Runtime commands require the Visor daemon started by visor start. Use visor status to inspect the daemon and Appium state, and visor stop when you are done.
Runtime execution requires a booted device target and a working Appium environment.

​
Next steps

Platforms and runtime

Review runtime defaults, daemon lifecycle behavior, and environment variables.

Scenarios

Learn how scenario files are structured and how visor validates them.

Artifacts and reports

See exactly which files visor writes after each run.

Command reference

Inspect every command, flag, and response field.