> ## 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.

# Getting started

> Install visor, check the local requirements, and run your first command.

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

<Steps>
  <Step title="Install visor from npm">
    ```bash theme={null}
    npm install -g visor-ai
    ```
  </Step>

  <Step title="Confirm the CLI is available">
    ```bash theme={null}
    visor --help
    ```

    This installs the `visor` CLI entry point and the runtime dependencies published with the `visor-ai` package.
  </Step>

  <Step title="Alternative: run from a source checkout">
    ```bash theme={null}
    npm install
    npm run build
    node dist/main.js --help
    ```
  </Step>
</Steps>

## Run your first command

Create a minimal scenario file named `checkout-smoke.json`:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
npm run verify
```

For only the local E2E layer, run:

```bash theme={null}
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:

```bash theme={null}
visor start --server-url http://127.0.0.1:4723
```

Then execute the same scenario:

```bash theme={null}
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:

```bash theme={null}
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.

<Warning>
  Runtime execution requires a booted device target and a working Appium environment.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Platforms and runtime" icon="smartphone" href="/platforms-and-runtime">
    Review runtime defaults, daemon lifecycle behavior, and environment variables.
  </Card>

  <Card title="Scenarios" icon="list-checks" href="/features/scenarios">
    Learn how scenario files are structured and how visor validates them.
  </Card>

  <Card title="Artifacts and reports" icon="folder-open" href="/features/artifacts-and-reports">
    See exactly which files visor writes after each run.
  </Card>

  <Card title="Command reference" icon="terminal" href="/reference/command-reference">
    Inspect every command, flag, and response field.
  </Card>
</CardGroup>