> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qaos.machdel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Starting a Run

> How to execute a QAOS test run from the command line.

## Basic usage

With a config file ready and the CLI authenticated, start a run:

```bash theme={null}
npx qaos run --config ./qaos-config.json
```

The CLI connects to the QAOS server, launches a headless browser, and begins executing tasks. Progress is streamed to your terminal in real time.

***

## Command options

```bash theme={null}
npx qaos run [options]
```

| Option            | Alias | Description                       | Default              |
| ----------------- | ----- | --------------------------------- | -------------------- |
| `--config <path>` | `-c`  | Path to the config JSON file      | `./qaos-config.json` |
| `--headed`        | `-h`  | Run with a visible browser window | Headless             |

### Default config lookup

If no `--config` flag is given, QAOS looks for `qaos-config.json` in the current working directory:

```bash theme={null}
npx qaos run  # uses ./qaos-config.json
```

### Headed mode

Use `--headed` (or `-h`) to open a visible browser window during the run. This is useful for:

* Debugging task descriptions that aren't producing expected behavior
* Watching the agent navigate your application
* Understanding how the agent interprets your pages

```bash theme={null}
npx qaos run --config ./qaos-config.json --headed
```

<Note>
  Headed mode may be slightly slower than headless mode. Use headless for production CI pipelines.
</Note>

***

## What happens during a run

<Steps>
  <Step title="Connection">
    The CLI connects to the QAOS server over WebSocket and sends your config to initiate the run. A run ID is assigned and printed.
  </Step>

  <Step title="Task execution">
    Tasks execute sequentially. For each task:

    * The browser navigates to `startUrl`
    * The agent analyzes the page (DOM, screenshots, network headers, cookies, console logs)
    * Subtasks are generated for interactive tests (e.g., attempting login with weak passwords)
    * Issues are detected and reported in real time
  </Step>

  <Step title="Agent evaluation">
    At each page, the selected subagents evaluate the page against their full issue catalog, using a combination of deterministic checks (fast, code-based) and LLM evaluation (deeper, context-aware).
  </Step>

  <Step title="Completion">
    Once all tasks finish, the CLI prints a summary of detected issues and a link to the full report in the dashboard.
  </Step>
</Steps>

***

## Real-time output

While the run is in progress, the CLI streams findings to your terminal as they are detected, and prints a summary with a link to the full report once the run completes.

***

## Running in CI/CD

QAOS works well in CI pipelines. Use API token authentication and a pre-committed config file:

```yaml GitHub Actions example theme={null}
- name: Run QAOS security audit
  run: |
    npx qaos auth --api ${{ secrets.QAOS_API_TOKEN }}
    npx qaos run --config ./qaos-config.json
  env:
    QAOS_API_TOKEN: ${{ secrets.QAOS_API_TOKEN }}
```

The CLI exits with code `0` on success and a non-zero code if the run fails or the server is unreachable.

***

## Known limitations

The QAOS agent runs as an automated browser and cannot perform every action a human user can:

| Limitation                   | Details                                                                                                                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **File uploads**             | Pages with file input fields are skipped. The agent cannot select or upload files from disk.                                                                                                     |
| **Third-party OAuth**        | "Sign in with Google / GitHub / etc." flows cannot be completed. Use a native username/password login or configure a mock OAuth provider in your test environment so the agent can authenticate. |
| **CAPTCHA / bot challenges** | Hard CAPTCHAs will block the agent. Disable them for your test environment or use an allowlisted IP.                                                                                             |
| **Bot detection**            | WAF rules, rate limiting, and browser fingerprinting may identify the agent as a bot and block navigation. Disable bot protection in your test environment before running.                       |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication error on startup">
    Your token may have expired or been revoked. Re-authenticate:

    ```bash theme={null}
    npx qaos auth --api <your-token>
    # or
    npx qaos auth --ui
    ```
  </Accordion>

  <Accordion title="Config file not found">
    Check the path you provided:

    ```bash theme={null}
    ls ./qaos-config.json      # verify it exists
    npx qaos run --config ./path/to/config.json
    ```
  </Accordion>

  <Accordion title="Browser fails to launch">
    QAOS requires Playwright browser binaries to be installed on your machine. Install them once before your first run:

    ```bash theme={null}
    npx playwright install chromium
    ```

    If the binaries are missing, QAOS will show an error message asking you to run the above command. After installing, simply retry your run.
  </Accordion>

  <Accordion title="Run times out">
    If your application loads slowly, consider adding descriptive context in your task config to help the agent understand the expected behavior. Each task has a generous timeout, but very slow pages may occasionally be skipped.
  </Accordion>
</AccordionGroup>