Skip to main content
qawolf flows run --env <env_id> is the recommended path. It runs your team’s flows from the local .qawolf/<env_id>/ 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 ahead of time.
Authenticate the CLI first. See Authenticate the QA Wolf CLI.

​
Run an environment

1
Find the environment’s ID — see Pull an environment.
2
From any directory, run:
The CLI:
  1. checks the local .qawolf/<env_id>/ 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 <env_id>. See Refresh a pulled environment.

​
Run a subset

Pass a glob pattern to limit which flows run:
With --env, the CLI matches patterns against the pulled cache under .qawolf/<env_id>/. Without --env, it matches patterns against both the current directory and the pulled cache.

​
Watch the browser

Pass --headed to see the browser window during a web run:
--headed does not apply to Android flows.

​
Capture artifacts on failure

By default, the CLI records no video or trace. To keep artifacts only when a flow fails, set the mode to retain-on-failure:
Artifacts land in .qawolf/output/ (or the directory set by --output-dir). To record HAR files of network traffic:
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

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

​
Stop after the first failure

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

​
Run web flows in parallel

--workers controls how many web flows run concurrently. Android flows only run one at a time — see --workers for the exact rule.

​
Write a JUnit XML report

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:
The CLI writes the XML report alongside the console output, independent of --json and --agent.

​
Run flows you authored locally

If you’ve scaffolded a local-only project with qawolf init, run without --env:
The CLI discovers flows matching **/*.flow.{ts,js} in the current directory and runs them against locally-installed runtime dependencies. See Install dependencies ahead of time if you need to install browsers or Android tooling explicitly.

​
Pull an environment

A run pulls for you, so you only need qawolf flows pull when you want the flow files without running them: to inspect them, commit them to a repository, or refresh a stale cache.
1
Find the environment’s ID in the QA Wolf app. Open Workspace settings → Environments and select the environment. Copy the id query parameter from the page URL: https://app.qawolf.com/<team_slug>/settings/environments?id=<env_id>. Use that value, not the environment’s display name.
2
Pull the flows:
The CLI writes flows to .qawolf/<env_id>/ by default. To use a different destination, pass --out:
3
List the pulled flows:

​
What pull writes

Inside .qawolf/<env_id>/, the CLI stores:
  • the flow source files
  • a manifest tracking what was pulled and when
  • an assets/ directory with the environment’s file assets from team storage, wired up so flows resolve them locally
  • a .env file with the environment’s variables, loaded automatically by qawolf flows run

​
Refresh a pulled environment

Run qawolf flows pull --env <env_id> again. The CLI prompts before overwriting any file you’ve modified locally. To skip the prompt and overwrite, pass --yes:

​
List flows on the platform

To see what is available on the platform without pulling, use --remote:

​
What’s not pulled

QA Wolf doesn’t download mobile app binaries. Mobile flows reference the APK or IPA build through an environment variable, so make sure that path points to a build available on the machine before running. Flows that read paths from runner-only QAWOLF_*_DIR environment variables also cannot resolve those paths locally; qawolf doctor flags both cases.

​
Install dependencies ahead of time

A run installs npm dependencies and Playwright browsers automatically before its first run, so web-only users rarely invoke qawolf install directly. A run doesn’t install Android dependencies; run qawolf install android before running Android flows. Use qawolf install to install ahead of time — for example, to warm a CI cache between the checkout step and the run step — or when running flows from a local-only project. From the project root, run:
The CLI scans the project for flows, looks at each flow’s target, and installs the dependencies required by every target it finds.

​
Install only for specific flows

Pass a pattern to limit which flows are considered:
This is useful in CI when a job only runs a subset of the suite.

​
Install browsers only

Equivalent to running playwright install for the browsers your web flows target.

​
Install Android dependencies only

Set ANDROID_HOME (or ANDROID_SDK_ROOT) to the path of your Android SDK before running this command. Install the SDK through Android Studio’s SDK Manager or the standalone cmdline-tools package.
The command installs the Appium uiautomator2 driver, downloads the Android system images for each target the matching flows use, and creates the corresponding AVDs.

​
iOS support

The CLI cannot yet execute iOS flows. qawolf install skips them with a warning. iOS support requires macOS with Xcode when it ships.

​
Exit codes

qawolf flows run exits with 0 when every flow passes and 1 when one or more fail. See Exit codes for the full list.

​
Limitations

  • Android flows must run with --workers 1. Only web flows run in parallel.
  • The CLI does not execute iOS flows. It skips them with a warning.
  • Flows that target the legacy "Basic" platform pull successfully, but the CLI cannot execute them.
  • The CLI skips flows where target is a computed value rather than a string literal, because it cannot determine the platform ahead of time.
Last modified on September 17, 2026