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

# Run flows locally

> Run your team's flows on your own machine — the CLI pulls, installs, and runs in one command.

`qawolf flows run --env <env>` is the recommended path. It runs your team's flows from the local `.qawolf/<env>/` cache, pulling them first only if they are not already cached locally, then installs the npm dependencies and Playwright browsers they need and runs them. Android flows require installing the Android tooling first with `qawolf install android`. See [Install dependencies](/qawolf/local-execution/install-dependencies).

<Check>
  Authenticate the CLI first. See [Authenticate the QA Wolf CLI](/qawolf/local-execution/authenticate).
</Check>

## Run an environment

<Steps>
  <Step>
    Find the environment's ID in your QA Wolf workspace under **Workspace settings → Environments**.
  </Step>

  <Step>
    From any directory, run:

    ```bash theme={null}
    qawolf flows run --env staging
    ```

    The CLI:

    1. checks the local `.qawolf/staging/` cache, and pulls the environment's flows only if they are not already cached
    2. loads the environment's `.env` file
    3. installs the npm dependencies and Playwright browsers the flows need
    4. runs every flow

    To refresh the local cache against the platform, run `qawolf flows pull --env staging`. See [Pull your team's flows](/qawolf/local-execution/pull-flows).
  </Step>
</Steps>

## Run a subset

Pass a glob pattern to limit which flows run:

```bash theme={null}
qawolf flows run --env staging "checkout/**"
qawolf flows run --env staging "src/flows/login.flow.ts"
```

With `--env`, patterns are matched against the pulled cache under `.qawolf/<env>/`. Without `--env`, patterns are matched against both the current directory and the pulled cache.

## Watch the browser

Pass `--headed` to see the browser window during a web run:

```bash theme={null}
qawolf flows run --env staging --headed
```

`--headed` does not apply to Android flows.

## Capture artifacts on failure

By default, no video or trace is recorded. To keep artifacts only when a flow fails, set the mode to `retain-on-failure`:

```bash theme={null}
qawolf flows run --env staging --video retain-on-failure --trace retain-on-failure
```

Artifacts land in `qawolf-output/` (or the directory set by `--output-dir`).

To record HAR files of network traffic:

```bash theme={null}
qawolf flows run --env staging --har retain-on-failure
```

By default the HAR captures headers and timing only. To include response bodies, pass `--har-content full`. Response bodies use significantly more memory and disk.

## Retry failing flows

```bash theme={null}
qawolf flows run --env staging --retries 2
```

The CLI retries each failing flow up to the given number of times. A flow that passes on retry is counted as a pass for exit-code purposes.

## Stop after the first failure

```bash theme={null}
qawolf flows run --env staging --bail
```

`--bail` is useful when iterating on a single flow and you want to fail fast.

## Run web flows in parallel

```bash theme={null}
qawolf flows run --env staging --workers 4
```

`--workers` controls how many web flows run concurrently. Android flows must run with `--workers 1` — the CLI errors out if Android flows are selected with a higher value.

## Write a JUnit XML report

```bash theme={null}
qawolf flows run --env staging --junit
```

The CLI writes a JUnit XML report to `qawolf-output/junit-report.xml` (or under the directory set by `--output-dir`). Pass an explicit path to override the default:

```bash theme={null}
qawolf flows run --env staging --junit ./reports/results.xml
```

The XML report is written alongside the console output and is independent of `--json` and `--agent`.

## Run flows you authored locally

If you've scaffolded a [local-only project](/qawolf/local-execution/set-up-a-project) with `qawolf init`, run without `--env`:

```bash theme={null}
qawolf flows run
```

The CLI discovers flows matching `**/*.flow.{ts,js}` in the current directory and runs them against locally-installed runtime dependencies. See [Install dependencies](/qawolf/local-execution/install-dependencies) if you need to install browsers or Android tooling explicitly.

## Exit codes

`qawolf flows run` exits with `0` when every flow passes and `1` when one or more fail. See [Exit codes](/qawolf/libraries/cli/api-reference/index#exit-codes) for the full list.

## Current limitations

* Android flows must run with `--workers 1`. Parallel execution is supported for web flows only.
* iOS flows are not executed. The CLI skips them with a warning.
* Flows that target the legacy `"Basic"` platform pull successfully but cannot be executed by the CLI.
* Flows where `target` is a computed value rather than a string literal are skipped because the CLI cannot determine the platform ahead of time.