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

​
Requirements

Before you install Visor, make sure you have:
  • Node.js 20 or later
  • npm
For your first run, you can use mock mode. Mock mode does not require Appium, a simulator, or a device. For real mobile runs, you also need:
  • a reachable Appium server, or permission for Visor to auto-start one
  • 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",
    "platform": "android"
  },
  "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 your first scenario

Once validation passes, execute the same scenario in mock mode: 
visor run checkout-smoke.json --mock --output artifacts-test
Mock mode is the safest first run because it produces deterministic output without depending on Appium or mobile device setup. 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/

​
Move to a real runtime

When you are ready to run against an actual app, keep the same scenario command shape and add your runtime inputs: 
visor run checkout-smoke.json \
  --platform android \
  --device emulator-5554 \
  --app-id com.example.app
If Appium is not already reachable, Visor attempts to start it unless you pass --no-auto-start-appium.
Real runtime execution requires a booted device target and a working Appium environment. If you only want to verify the CLI and report flow, stay in --mock mode first.

​
Next steps

Platforms and runtime

Review runtime defaults, Appium 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.