QA Wolf CLI

qawolf runs QA Wolf flows locally, calls the QA Wolf public API, and drives interactive runners: live cloud pods holding a browser you can see and act on.

This file is an overview, not a reference. Before first using a command whose flags are not shown here, run qawolf <command> --help once. The installed CLI is authoritative for flags and always matches its version; reuse that syntax for the rest of the task.

Auth

Commands that talk to QA Wolf authenticate via the QAWOLF_API_KEY environment variable (or stored credentials from qawolf auth login). read and write commands require auth; local commands do not, unless their table entry notes a flag that switches them to read. Verify with qawolf auth whoami. Never print or log the key.

A team API key in the environment is the whole credential, including for the runner group. Nothing needs a browser login, a session token or a held connection, so a sandbox that can set one environment variable and make requests to one host can do everything below.

Commands use https://app.qawolf.com by default. Set QAWOLF_HOST_URL to target another deployment host, for example https://app.staging.example.com. QAWOLF_API_URL is a separate API endpoint and does not select the deployment host used by CLI commands.

Resolve the target environment once per task. Use QAWOLF_ENVIRONMENT when it is set; otherwise select an id or alias from qawolf --json environment find and reuse it. Shell invocations may not share exported variables, so pass the selected environment explicitly instead of rediscovering it. Check the command's help for its environment flag: variable commands use --environment-id; qawolf flows run uses --env.

If multiple environments are returned and the task context does not identify the target, ask instead of guessing. Do not default to the newest environment.

qawolf environment listVariableNames intentionally returns names only. A listed name is enough to reference process.env.NAME in flow code; do not ask for its value merely because the CLI does not return it.

Interactive runners cost money

An interactive runner is a live pod holding a browser, and it is billed while it runs. qawolf runner launch starts one; qawolf runner run starts one too when no runner is already available, and says so when it does. Reading a runner counts as activity, so qawolf runner events --follow left open keeps it alive and billing. qawolf runner terminate is what ends it, so terminate a runner you launched rather than leaving it to time out.

qawolf runner launch remembers its runner as this directory's default, so the commands that follow need no --runner. Override that default for one command with --runner <id>, or for a whole session with QAWOLF_RUNNER_ID.

Output

When consuming output programmatically, always pass --json (or --agent). Human-formatted output is not stable across versions. Errors go to stderr; a non-zero exit code means the command failed. Reuse successful read results within a task unless a relevant write or target change could make them stale.

One exception to know about: on qawolf runner events, --json also switches each printed line from the payload alone to the whole envelope (sequence, recordedAt, payload). Both are JSON. Pass it when you want to page by sequence, omit it when you want the payloads themselves.

A --json response shows you most of its own shape, so read it first.

qawolf run get is the exception worth reading about before you use it. Its artifact URLs expire, its failure fields are absent from a passing run, and its traceUrl downloads a Playwright trace that you can read as JSON without opening the trace viewer. Read references/run-results.md before reporting on a run's outcome or opening its trace.

Safety: reads vs writes

Read commands do not change team data, but some have operational effects noted in their command entry. Write commands act on the real team. Do not invent configuration or write speculative values; write only when requested or when the task requires missing configuration whose exact value is known. A successful write response is confirmation, so do not read immediately only to verify it. Never blind-retry a write on timeout: it may have reached the server the first time.

Two runner-specific costs to keep in mind. Launching a runner starts a billed pod, so reuse one id rather than minting new ones per step, and stop a runner when you are done. And run, act and exec may all have taken effect even when their answer never arrives, so none of them is safe to blind-retry; run is the expensive one, because a second submission bills a second run.

Git-backed workflows

Inspect git status before publishing. Stage and commit only files changed for the current task, preserve unrelated worktree changes, then push the task's current branch.

Commands

Kinds: read calls the QA Wolf API without changing anything; write changes team state; local only affects this machine. A parenthesized note like local (read with --remote) means that flag makes the command call the QA Wolf API and require auth.

Driving a browser: the runner group

The runner commands drive a live cloud browser: launch one, screenshot to see it, act to click and type, run a flow on it, exec a snippet against its page, events to read its journal (including the recorder stream, which turns your actions into Playwright locators), keepalive to hold it open, and terminate when done. Everything is a plain request to one host, so a shell with an API key and its own vision model can close the see-and-act loop with no other tooling.

The full workflow is its own guide: how a runner is billed, why the first call must be a run, the order the commands go in, the see-and-act loop, exec, the recorder, reading history, staying alive, and an end-to-end example. Read references/runner.md before driving a runner for the first time.