QA Wolf CLI: run QA Wolf flows from your terminal or CI

What the qawolf CLI actually runs, and what it does not

The CLI is a local execution and management client for QA Wolf flows. The README is explicit that flow creation, AI-powered test generation, managed cloud execution and team collaboration belong to the full QA Wolf platform, not to this repository. So the open source surface here is the runner and the commands around it, not a self-contained test authoring system.

That shapes who the tool is for. If your team already has flows on the platform, the CLI gives you a way to execute them from a terminal, from a CI job, or from an AI agent harness without going through a browser dashboard. If you are an individual developer looking for an open source end-to-end testing framework to adopt from scratch, this is the wrong entry point: you still need a QA Wolf account, and the README points you to qawolf.com to get started.

The repository is Apache-2.0, published on npm as @qawolf/cli, and the last push was on 2026-09-10. Releases v1.24.0 through v1.26.0 landed between 2026-09-08 and 2026-09-10, so the project is being cut frequently, though release cadence alone says nothing about whether a given flow will pass.

The local cache and the pull-before-run data flow

The mechanism worth understanding before you install anything is the local cache. `qawolf flows run --env <env-id>` executes your team's flows from a per-environment copy on disk under `.qawolf/<env>`. The README states that the CLI pulls flows first only if they are not already cached locally, and installs the runtime dependencies those flows need.

That design has a practical consequence. A run is not guaranteed to reflect the latest state of your flows on the platform, because a cached copy short-circuits the pull. When you want the local copy refreshed, you run `qawolf flows pull --env <env-id>` explicitly. If a teammate changed a flow and your CI job still runs the old one, the cache is the first thing to check, not the flow itself.

The environment identifier comes from the QA Wolf dashboard under Settings, Environments. Authentication is either interactive through `qawolf auth login` or non-interactive through the `QAWOLF_API_KEY` environment variable, which is the path for CI. The `qawolf install` command handles the browser runtime as a separate, one-time step, which means a container that skips it will fail at run time rather than at install time.

Installing the qawolf CLI and running a first flow

The package installs globally through any of the major Node package managers. Node 20.19 or newer is required. The README notes that Node 20 reached end-of-life on 2026-04-30 and no longer receives security updates, and that it remains supported here only for environments still pinned to it, with Node 22 or later preferred.

npm install -g @qawolf/cli
# or: pnpm add -g @qawolf/cli
# or: yarn global add @qawolf/cli
# or: bun add -g @qawolf/cli

You can check the command surface without installing anything permanently:

npx @qawolf/cli --help

If Node is not available in your environment at all, precompiled binaries are attached to each GitHub release for linux-x64, linux-arm64, darwin-x64, darwin-arm64 and windows-x64. The README gives this download example for Apple silicon:

curl -fsSL -o qawolf https://github.com/qawolf/cli/releases/latest/download/qawolf-darwin-arm64
chmod +x qawolf && ./qawolf --help

With the CLI available, authenticate and run your team's flows against an environment. The `<env-id>` value comes from the dashboard under Settings, Environments.

qawolf auth login                  # or set QAWOLF_API_KEY for CI
qawolf flows run --env <env-id>

To try the tool against something that does not depend on your own flows, the repository ships samples in `examples/`. The README's sequence installs the browser runtime once and then runs a file directly:

qawolf install   # one-time: install the browser runtime
qawolf flows run examples/example.flow.ts

If you want to author flows locally without the platform, the README says to run `qawolf init` first. When something misbehaves, `qawolf doctor` is the diagnostic command, and each command accepts `--help` for its own flags.

The Runner SDK and its two kinds of failure

Beyond the command line, the package exports a TypeScript entry point at `@qawolf/cli/runner-sdk` for driving interactive runners programmatically. The design choice the README highlights is that every verb names the runner it addresses, so nothing is launched or billed implicitly. That matters if you are wiring runs into an agent or a service where an accidental launch has a cost.

import { createRunnerSdk } from "@qawolf/cli/runner-sdk";

const runner = createRunnerSdk({ apiKey: process.env.QAWOLF_API_KEY });

await runner.launch({ id: "agent-1", runnerFamily: "default" });

const submitted = await runner.run({
  entryPointPath: "src/flows/smoke.flow.ts",
  environment: "ambient",
  runnerId: "agent-1",
  selection: "whole-flow",
});
if (submitted.ok) console.log(submitted.value.runId, submitted.value.fileSync);

The error model is the interesting part, and it is easy to get wrong. According to the README, `ok: false` means a transport or authentication failure. A runner that refused the request is not an error at that level: it returns `ok: true` with `value.outcome === "failure"` and a `failureReason` drawn from the published contract. Code that only checks `ok` will treat a refused run as a success. The README's phrasing is that a caller can switch on the outcome exhaustively, which is a hint that the failure reasons are meant to be enumerated rather than string-matched.

The SDK types are shipped in the package under `dist/types/runnerSdk/`, and the build includes a types gate script, so consumers importing the SDK get declarations rather than `any`.

Where the qawolf CLI is the wrong tool

The clearest limitation is the one the README states up front: this is not the platform. AI-powered test generation, managed cloud execution and team collaboration are not in this repository. If your goal is to write end-to-end tests with AI assistance and have them run on managed infrastructure, the CLI is a client for that service, not a replacement for it.

The second limitation is the cache. Because `flows run` skips the pull when a local copy exists, a stale `.qawolf/<env>` directory can produce results that do not match the platform. There is no automatic refresh described in the README, so the burden is on your pipeline to call `qawolf flows pull --env <env-id>` when freshness matters. A CI job that never pulls is testing yesterday's flows.

The third is runtime setup. The browser runtime is installed by a separate `qawolf install` step. Nothing in the README suggests it runs implicitly before a flow, so an ephemeral container needs that step baked into the image or scripted ahead of the run.

Finally, the README points to docs/known-issues.md for current limitations and workarounds rather than listing them inline. That is a reasonable place to keep them, but it means the README alone does not tell you what is currently broken. If your evaluation stops at the README, you have not read the limitation list.

How it compares with running Playwright directly

The obvious alternative for a team that wants local and CI end-to-end execution is Playwright itself, which the project lists as a topic and which the flows are built around. The difference in approach is where the test definitions live and who owns them.

With Playwright, the test files are the source of truth in your repository, the runner is the same package you installed, and there is no account, no environment identifier and no server-side copy to reconcile. You get full control over caching because there is no cache layer between you and the tests.

With qawolf/cli, the platform holds the flows and the CLI keeps a per-environment copy on disk. You gain platform features such as AI generation and managed cloud execution, and you gain a single command that runs your team's flows by environment rather than by file path. You give up the property that what is on disk is always what runs, unless you pull first. For a team already on QA Wolf, that trade is the point of the tool. For a team that only wants a local runner, it is overhead with no matching benefit, since the authoring side is not in this repository.

Agent integration, licence and the cost of upgrading

The repository ships a `qawolf-cli` Agent Skill under `skills/qawolf-cli/SKILL.md` that follows the Agent Skills specification. The README lists compatible harnesses including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode, and shows installation through the cross-harness `skills` installer after the CLI itself is installed globally.

npm install -g @qawolf/cli
npx skills add qawolf/cli --skill qawolf-cli --global

The installer detects supported harnesses and prompts for a target; passing `--agent` flags with `--yes` makes it non-interactive, and omitting `--global` scopes the skill to the current project. One maintenance detail worth knowing: the skill is generated from a source template and the command tree via `bun run generate`, and the test suite keeps it in sync. So the skill file is a build artifact, not hand-written documentation, and it should track command changes automatically.

On licensing, the package is Apache-2.0 and published to npm with public access. That permits commercial use and modification under the usual Apache terms, including its patent grant and notice requirements. This is a description of the licence identifier, not legal advice; if you are redistributing a modified binary, read the LICENSE file in the repository.

Upgrade cost is mostly a Node version question. The floor is Node 20.19, and the README recommends Node 22 or later because Node 20 is past end-of-life. The package ships standalone binaries for five platform targets, which is what you use when the Node floor is inconvenient. The release history shows several versions in a single week, so pinning a version in CI and reviewing the changelog before bumping is the lower-risk path.

Editorial conclusion

Adopt qawolf/cli if your team already has flows on the QA Wolf platform and you want them executed from a terminal, a CI job, or an agent harness, and you are comfortable with the hosted dependency. Do not adopt it as a standalone open source Playwright runner: flow creation, AI test generation and managed cloud execution are platform features, and the README says so. Before committing, verify that your CI image satisfies Node 20.19+ or use one of the precompiled release binaries, and read docs/known-issues.md for the limitations the README points to rather than lists.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. qawolf/cli on GitHub
4. README
5. Releases