QA Wolf CLI: running team flows locally without the platform UI

The gap this fills: your flows are on the platform, your pipeline is not

QA Wolf flows live on the QA Wolf platform, where they are created, generated with AI assistance and executed in managed cloud runs. That is fine until an engineer wants the same flows to run inside a build step, a pre-merge check or a debugging session on a laptop. The CLI is the piece that closes that gap. It runs and manages flows locally, and the README is explicit that flow creation, AI-powered test generation, managed cloud execution and team collaboration stay on the platform. So the audience is narrow and specific: teams that have already bought into QA Wolf and now need a local execution path, not teams shopping for an end-to-end testing framework. If you have no QA Wolf account, nothing in this repository will run a browser test for you.

The local cache is the whole design, and it explains the command set

The mechanism that matters is the cache. According to the README, qawolf flows run --env <env-id> executes your team's flows from the local .qawolf/<env> cache, described as a per-environment copy of your flows on disk. Flows are pulled first only if they are not already cached, and the runtime dependencies they need are installed at that point. That single sentence explains most of the command surface. qawolf flows pull --env <env-id> exists to refresh that copy when you want newer flows rather than whatever is on disk. qawolf install handles runtime dependencies as a separate, one-time step, which the examples use before running a sample flow. qawolf init sets up a local-only project for authoring flows without the platform. The data flow is therefore: platform holds the source of truth, the CLI materialises a per-environment snapshot under .qawolf/, and execution reads from the snapshot. The consequence is that a stale cache is a real state you can be in, and the README names the remedy rather than hiding it.

Getting to a first run: auth, environment id, and one command

The README gives a short path. Install globally with npm install -g @qawolf/cli, or use pnpm, yarn or bun equivalents, or skip installation entirely with npx @qawolf/cli --help. Then authenticate with qawolf auth login, or set QAWOLF_API_KEY for CI so no interactive login is needed. The environment id comes from the QA Wolf dashboard under Settings, Environments. The first real run is qawolf flows run --env <env-id>. To run the bundled samples instead, the examples directory works after a one-time qawolf install followed by qawolf flows run examples/example.flow.ts. There is also a qawolf doctor command for diagnosing problems, which is the first thing to reach for when a run fails for reasons that are not obvious from the output. Every command accepts --help for its flags, and the README points to a full command and flag reference, a configuration reference for qawolf.config.ts fields, an environment variables page and an exit codes page in the docs site. Note the Node requirement: 20.19 or newer, with a stated preference for 22+ because Node 20 reached end-of-life on 2026-04-30 and no longer receives security updates.

Standalone binaries remove Node from the equation

Precompiled binaries are attached to each GitHub release: qawolf-linux-x64, qawolf-linux-arm64, qawolf-darwin-x64, qawolf-darwin-arm64 and qawolf-windows-x64.exe. The README shows a curl against the latest release download URL for the darwin arm64 build, followed by chmod +x and ./qawolf --help. This matters for a practical reason: a CI image that does not carry a supported Node runtime can still run flows, and you avoid pinning a Node version purely to satisfy a test client. The trade-off is that you now own binary updates yourself. Nothing in the supplied material describes an auto-update path for the standalone builds, so a team using them needs its own mechanism to notice and fetch new releases. The npm route gets updates through the package manager instead.

The Runner SDK treats refusal as a value, not an exception

For programmatic use there is a Runner SDK imported from @qawolf/cli/runner-sdk. The README example creates a client with createRunnerSdk({ apiKey: process.env.QAWOLF_API_KEY }), launches a runner with runner.launch({ id: "agent-1", runnerFamily: "default" }), then calls runner.run with an entryPointPath, an environment, a runnerId and a selection of "whole-flow". The design note in the README is the interesting part: every verb names the runner it addresses, so nothing is launched or billed implicitly. Error handling is split deliberately. A result with ok: false means a transport or auth failure. A runner that refused the request comes back as ok: true with value.outcome === "failure" and a failureReason drawn from a published contract, so a caller can switch on it exhaustively. That distinction is worth taking seriously when you write CI logic: retrying an ok: false result is a different decision from retrying a refusal, and the SDK is shaped so you cannot conflate them by accident.

Where the CLI stops: no account, no flows, no local-only generation

The clearest limitation is stated in the README itself. Flow creation and AI-powered test generation are platform features. The CLI runs and manages flows locally; it does not produce them, except through the local-only project path that qawolf init sets up, which the README describes as authoring flows locally without the platform. If your goal is a self-contained open source Playwright wrapper that records and generates tests on your own machine, this is the wrong tool, because the generation half is not in the repository. A second boundary is the account requirement: you need a QA Wolf account and an environment id from the dashboard before the first run, and the CI path needs QAWOLF_API_KEY. A third is the cache: because runs read from .qawolf/<env> and only pull when flows are absent, a flow edited on the platform will not appear until you run qawolf flows pull --env <env-id>. That is a deliberate speed choice with a correctness cost, and the README points to a known-issues document for current limitations and workarounds rather than claiming there are none.

Compared with plain Playwright, the difference is where the flows live

Playwright is the obvious reference point, and the topics list here includes playwright. The difference is not the browser automation layer, it is ownership of the test artifacts. With Playwright you install @playwright/test, write specs in your own repository, and the suite is versioned, reviewed and executed entirely under your control. With qawolf/cli the flows are the team's flows on the QA Wolf platform, and the local .qawolf/<env> directory is a cache of them, refreshed on demand. That buys a shared source of truth across a team and a managed execution path for the same flows, which is the reason to choose it. It costs you a dependency on an external account and a network pull before the local copy is current. If your tests must be reproducible from a git clone with no external service, Playwright alone is the simpler answer. If your organisation has already standardised on QA Wolf for authoring and cloud runs, the CLI is the way to get those same flows into a pipeline without duplicating them.

Agent skill, licence and what a version bump costs you

The repository ships a qawolf-cli Agent Skill at skills/qawolf-cli/SKILL.md that follows the open Agent Skills specification, and the README lists compatible harnesses including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode. Installation goes through the cross-harness skills installer: npx skills add qawolf/cli --skill qawolf-cli --global, with --agent flags and --yes for non-interactive targeting, and omitting --global to scope it to the current project. The skill also ships inside the npm package. The README states the skill is generated from a source template at src/commands/qawolfCliSkill.template.md plus the command tree via bun run generate, and kept in sync by the test suite, so a command added without regenerating the skill should be caught before release. On maintenance: releases are frequent, with v1.24.0, v1.25.0 and v1.26.0 all landing within three days in the supplied release list, which means a pinned version drifts quickly and you should decide deliberately between pinning and tracking. The licence is Apache-2.0, a permissive licence that permits commercial use and modification; the repository carries a LICENSE file and a SECURITY.md for vulnerability reports. Nothing here is legal advice, and Apache-2.0 includes a patent grant and notice obligations that your own counsel should review if you redistribute the binary.

Editorial conclusion

Adopt qawolf/cli if your team already runs QA Wolf flows on the platform and you want them executed from a terminal or CI job against the local .qawolf/<env> cache. Do not adopt it as a standalone open source browser testing framework: flow creation, AI test generation and cloud execution are platform features, and the CLI needs a QA Wolf account and an environment id from the dashboard. Verify first that your Node version satisfies the 20.19+ requirement (prefer 22+, since Node 20 is past end-of-life), that a QAWOLF_API_KEY or an interactive auth login is available to your CI runner, and that the known-issues document does not already list your failure mode.

Official sources

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