Skip to main content
Run qawolf help to list every command, or qawolf <command> --help for one command’s options. The installed CLI’s help always matches its version.

auth

Manages authentication with the QA Wolf platform. The CLI uses the first credential it finds: the QAWOLF_API_KEY environment variable, then a stored API key, then a browser session from qawolf auth login.

auth login

Signs you in to QA Wolf, and asks whether to use a browser or an API key. Requires an interactive terminal — in non-interactive contexts, set QAWOLF_API_KEY directly.
  • Browser — shows a one-time code and opens a sign-in page. After you sign in, the CLI asks which organization and workspace to work in when you can reach more than one. Set QAWOLF_ORGANIZATION or QAWOLF_WORKSPACE to choose without a prompt.
  • API key — prompts for a key, validates it against the platform, and stores it in the system keychain, or in a config file when the keychain is unavailable.
An API key takes precedence over a browser session. If one is set or stored, the CLI says so before a browser sign-in starts. With a browser sign-in or a user API key, auth login also sets up Git to use your QA Wolf sign-in. Then git clone, git fetch, and git push work with your workspace’s QA Wolf Git URL without asking for a password. The CLI adds a credential helper for the QA Wolf host to your global Git config and prints the lines it added. See Clone your workspace with Git. The CLI skips Git setup when Git isn’t installed, when the CLI runs through npx or bunx, and when you sign in with a team API key, which Git can’t use. Example:

auth logout

Removes stored credentials: the stored API key and the browser session. Also removes the Git credential helper that auth login added. This command cannot remove credentials set via the QAWOLF_API_KEY environment variable. Example:

auth switch

Chooses which organization and workspace a browser session works in, without signing in again. Requires a browser sign-in from qawolf auth login. The CLI saves the choice for every session on this machine. To work in another workspace for one runner command without saving it, pass --workspace-id to that command instead. In a non-interactive shell, set QAWOLF_WORKSPACE to the workspace’s name, slug, or ID. If workspaces in more than one organization match, also set QAWOLF_ORGANIZATION to the organization’s name or ID. Examples:

auth whoami

Displays the authenticated workspace name, ID, optional slug, and the credential source. Example:

flows

Manages and runs QA Wolf flows.

flows run [pattern]

Runs flows matching [pattern], or every flow when omitted. The default pattern matches **/*.flow.{ts,js} in the current working directory and in .qawolf/<env_id>/ subdirectories. Examples:
Options:
  • --retries <n> — number of retries for each failing flow. Default: 0.
  • --bail — stop after the first failure. Default: false.
  • --workers <n> — parallel worker count for web flows. Default: 1. Android flows must run with --workers 1; the CLI errors out if Android flows are selected with a higher value.
  • --timeout <ms> — default timeout for actions and assertions, in milliseconds. Default: 30000.
  • --junit [path] — write a JUnit XML report. With no value, writes to <output-dir>/junit-report.xml. Pass an explicit path to override.
  • --video <mode> — on, off, or retain-on-failure. Default: off.
  • --trace <mode> — Playwright trace mode. on, off, or retain-on-failure. Default: off.
  • --har <mode> — HAR capture mode. on, off, or retain-on-failure. Default: off.
  • --har-content <mode> — omit or full. full includes response bodies and uses more memory. Default: omit.
  • --output-dir <path> — directory for run artifacts (videos, traces, HAR). Default: .qawolf/output.
  • --headed — show the browser window instead of running headless. Default: false.
  • --env <env> — the id or alias of an environment. When set, the CLI pulls missing flows before the run. If the platform can’t be reached, it runs the flows already pulled. See where to find it.
  • --tag <name> — run only the flows carrying this tag. Repeat it to run flows carrying any of several tags. Without --env, matches against the tags the last flows pull cached.
  • --all-envs — when a tag matches flows in more than one pulled environment, run every match instead of choosing one. Default: false.
  • --allow-no-match — exit 0 instead of 2 when the pattern selects no flow to run. Default: false.
  • --deps <dir> — use this prepared dependency directory instead of installing the runtime automatically. To move the managed runtime instead, set QAWOLF_RUNTIME_DIR.
  • --no-browser-deps — skip installing the operating system’s browser dependencies, which on Linux needs root. The system libraries must already be installed.
Exit codes: 0 when all flows pass, 1 when one or more flows fail, 2 for invalid arguments, an unrecognized flow target, or a pattern that selects no flow. See Exit codes.

flows list [pattern]

Lists flows matching [pattern]. By default, lists local flows; with --remote, lists flows from the QA Wolf platform. Examples:
Options:
  • --remote — list flows from the QA Wolf platform instead of the local project. Default: false.
  • --env <env> — with --remote, the id or alias of the environment to list. Defaults to QAWOLF_ENVIRONMENT, or a picker in an interactive terminal. Without --remote, the slug or id of a pulled environment.
  • --tag <name> — list only the flows carrying this tag. Repeat it to list flows carrying any of several tags. Without --remote, matches against the tags the last flows pull cached.
  • --include-drafts — with --remote, include draft flows. Default: false.

flows pull

Downloads an environment’s flows into the local .qawolf/<env_id>/ cache. The directory takes the environment’s ID even when you pass an alias. Examples:
Options:
  • --env <env> — the id or alias of the environment to pull from. Defaults to QAWOLF_ENVIRONMENT, or a picker in an interactive terminal. See where to find it.
  • --out <path> — destination directory. Defaults to .qawolf/<env_id>/.
  • --yes — overwrite locally-modified files without prompting. Default: false.

install

Installs every runtime dependency the project’s flows need. With a [pattern] argument, it installs only the dependencies for the matching flows. Examples:
Options:
  • --no-browser-deps — skip installing the operating system’s browser dependencies, which on Linux needs root. The system libraries must already be installed.

install browsers [pattern]

Installs the Playwright browsers used by the project’s web flows. Examples:
Options:
  • --no-browser-deps — skip installing the operating system’s browser dependencies, which on Linux needs root. The system libraries must already be installed.

install android [pattern]

Installs Android system images, AVDs, and the Appium driver used by the project’s Android flows. Requires ANDROID_HOME or ANDROID_SDK_ROOT. Examples:

install clear

Removes the managed runtime cache, which holds every runtime version the CLI has installed. Asks for confirmation in an interactive terminal. When QAWOLF_RUNTIME_DIR is set, the cache is in that directory. Examples:
Options:
  • --yes — skip the confirmation prompt. Default: false.

init

Scaffolds a QA Wolf project in the current directory. Creates qawolf.config.ts, an example flow at src/flows/example.flow.ts, and .qawolf/.gitignore. When no package.json exists, offers to create one with "type": "module", the @qawolf/flows dependency, and a test:e2e script that runs qawolf flows run. When one already exists, offers to add whichever of those it lacks. Examples:
Options:
  • --yes — overwrite existing files and make the package.json changes without prompting. Default: false.

doctor

Diagnoses problems running flows locally. Checks your environment (CLI and Node.js versions, API key, connectivity) and the dependencies your flows need, such as Playwright browsers and the Android SDK. Examples:
Options:
  • --all — run every platform check, including platforms the project does not use. Default: false.

runner

Launches and drives a browser, an Android device, an iOS device, or a Windows desktop hosted by QA Wolf. Nothing runs on your machine. For a walkthrough, see Drive a runner. Every subcommand except launch and list targets a runner in this order: --runner <id>, then the QAWOLF_RUNNER_ID environment variable, then the runner that qawolf runner launch stored for the current directory. If none of these names a runner, run, act, actions, and exec launch a new browser runner, which bills while it’s up, and say so on stderr. Every subcommand takes --workspace-id <id>, which works in that workspace for the one command and isn’t saved. Without it, runner commands use the workspace that qawolf auth switch saved.

runner launch

Launches a runner and stores it as the current directory’s default. Examples:
Options:
  • --id <id> — the runner’s id, chosen by you: up to 63 lowercase letters, digits, and dashes, starting and ending with a letter or digit. Launching an id that is already running reconnects to that runner instead of starting a second one. Without --id, the CLI generates a random id.
  • --name <family> — what the runner runs: playwright for a browser, android, ios, or windows. See Windows desktop testing before launching a Windows runner. Default: playwright.

runner list

Lists the runners running in your workspace. Examples:
Options:
  • --here — list only the runners launched from the current directory, or named by QAWOLF_RUNNER_ID. Default: false.

runner terminate

Ends a runner and the pod it runs on. Succeeds when no runner was running, and never launches one. Examples:

runner stop-run

Stops what a runner is executing and leaves the runner up, its browser on whatever page the run reached. The run settles as stopped, not passed or failed. To end the runner itself, use runner terminate. Succeeds when nothing was running. Example:

runner keepalive

Resets a runner’s inactivity clock. QA Wolf ends a runner after a period of inactivity, and every command that talks to the runner counts as activity. Use keepalive when you pause for minutes between actions. It keeps a billed runner alive, and it never launches one. Examples:

runner run <flowFile>

Runs a flow on a runner. Sends the flow file, the files it imports, and your package.json and tsconfig.json. On an Android, iOS, or Windows runner, the first run starts the device or desktop session, so run a flow before you take screenshots or act on it. The flow’s target has to match what the runner runs. Examples:
Options:
  • --follow — wait for the run to finish and report its status. Exits 1 if the run did not pass. Default: false.
  • --logs — stream the run’s log lines while following. Implies --follow.
  • --run-events — stream the run’s progress events as JSON lines while following. Implies --follow.
  • --recorder-events — stream the browser actions the runner records as JSON lines while following. The recorder covers the whole runner, so the stream starts just before the run is submitted. Implies --follow.
  • --env-id <env> — the id or alias of the environment whose variables the run gets. Defaults to QAWOLF_ENVIRONMENT unless you pass --env-file.
  • --env-file <path> — a dotenv file whose variables the run gets. With --env-id, its variables go on top of the environment’s.
  • --env-var <name=value> — one variable for this run only, on top of the environment and --env-file. Repeat it for several. --var is an alias.
  • --builds <ids...> — builds to install in this run, one per app and platform. Each replaces the environment’s latest build of its app and platform. Put the flow file before this flag.
  • --lines <start-end> — run only these lines, counted from 1, against the runner’s current page, instead of the whole flow.
  • --lines-file <path> — the file --lines refers to, such as a page object. Requires --lines. Defaults to <flowFile>.
  • --timeout <seconds> — stop following after this long. Default: 3600.

runner events <stream>

Prints a runner’s journal, one entry per line. QA Wolf writes five streams: console, recorder, run-events, run-logs, and run-status. A stream nobody has written reads as empty. This command never launches a runner. As you drive the browser, the recorder stream records each interaction. Its entries carry the Playwright locator the runner resolved (locator), the other locators that matched the same element (alternates), and the generated Playwright call (code). With --json, each line is the whole entry (sequence, recordedAt, and payload) instead of the payload alone. Examples:
Options:
  • --tail <count> — read only the newest <count> entries.
  • --since <sequence> — read the entries after this sequence.
  • --run <id> — limit the run-scoped streams to one run.
  • --follow — keep reading as new entries arrive. Reading counts as activity, so a follow keeps the runner alive and billing. Ends only at --timeout, with exit code 6, not when a run settles. Default: false.
  • --timeout <seconds> — stop following after this long. Default: 3600.

runner screenshot

Saves a JPEG of the runner’s screen. Example:
Options:
  • --out <path> — the file to write. - writes the image to stdout and moves the confirmation, JSON included, to stderr. Default: screenshot.jpg.

runner act <action>

Performs one action on the runner’s screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate, and type. A mobile runner takes tap, swipe, fill, and type. Use - as the action to read a whole action as JSON from stdin. Examples:
Options:
  • --x <pixels>, --y <pixels> — the point to act on, in screenshot pixels.
  • --selector <selector> — tap or fill: the element to act on. tap takes it in place of --x and --y.
  • --strategy <strategy> — how --selector is resolved: xpath, ios-predicate, or shadow. Default: xpath.
  • --text <text> — type: the text to type into what has focus. fill: the field’s new value.
  • --from <x,y>, --to <x,y> — swipe: the start and end points.
  • --duration-ms <ms> — swipe: how long it takes, up to 10000.
  • --scroll-x <delta>, --scroll-y <delta> — scroll: the horizontal and vertical wheel deltas. The one you leave out is 0.
  • --path <json> — drag: a JSON array of the points to drag through.
  • --button <button> — click: left, right, wheel, back, or forward. Default: left.
  • --keys <keys...> — keypress: modifiers and the key, for example Control a.
  • --url <url> — navigate: the http or https URL to go to.
  • --screenshot <path> — also save a screenshot taken after the action, even when the action did not take effect. - writes it to stdout and moves the confirmation, JSON included, to stderr.

runner actions <sequence>

Performs up to ten actions in one request, as a JSON array of the actions runner act takes. Use - to read the array from stdin. Examples:
Options:
  • --screenshot <path> — save a screenshot taken after the last action. - writes it to stdout and moves the confirmation to stderr.
  • --screenshot-mode <mode> — none, final, or each. each saves one screenshot per action, with the action’s index before the extension: step-0.jpg, step-1.jpg, and so on. Default: final with --screenshot, none without it.
  • --continue-on-failure — carry on past an action that reached the runner but did not take effect. A runner that can’t be reached still ends the sequence. Default: false.

runner exec <file>

Evaluates a snippet against the runner’s live page. Use - to read the snippet from stdin. exec reports whether the snippet ran, not what it returned. To get a value back, print it and read the console stream with runner events console. Entries from your snippet carry "source": "serverConsole", and entries from the page carry "source": "browserConsole". A snippet that changes something may have run even when exec exits 4, so check its effect before you run it again. Examples:
Options:
  • --file <path> — evaluate the snippet in this file’s scope, so it can use your page objects and helpers. Sends the file and the other files in its directory. Without it, the snippet imports nothing of yours.

runner inspect

Reads one thing off the runner’s live page or Appium session and prints it to stdout. Examples:
Subcommands:
  • element-html — browser only. The HTML of the first element the required --selector matches.
  • page-html — browser only. The page’s HTML, simplified. --selector limits it to one subtree.
  • variable — a top-level variable from the running flow, named by --name.
  • session — mobile only. Whether the Appium session is ready.
  • contexts — mobile only. The WebView contexts available, and which one is current.
  • page-source — mobile only. The current context’s page source, or another context’s with --context <name>.
  • elements — mobile only. The elements at --x and --y, carrying --text, or matching --selector. --partial matches text that contains --text. --strategy resolves --selector the way it does for runner act, and --context <name> reads another context.

runner import-package <name>

Installs an npm package into the runner’s live run, so runner exec snippets and runner run --lines selections can import it without a full run. Resolves the package against your project’s dependencies in package.json. Needs a run already going on the runner. Examples:
Options:
  • --package-version <version> — the version to install. Default: latest.

runner highlight-selector [selector]

Highlights what a selector matches on the runner’s live page, so the next runner screenshot shows it. The highlight stays until you replace or clear it. Omit the selector to clear it. Prints how many elements matched, and exits 0 even when none did. Exits 2 when the page can’t read the selector, or when the runner has no browser to draw on. Examples:

runner promote-snapshot

Accepts a run’s screenshot as the new baseline for a failed image diff, on the runner that produced the run. Both paths come from the diff’s imageDiffArtifact event in the run-events stream. They’re paths in the run’s screenshot storage, not files on your machine. Promoting the same screenshot twice is safe. Examples:
Options:
  • --screenshot <path> — required. The screenshot to promote, as the image diff named it.
  • --baseline <path> — required. The baseline to replace, as the image diff named it.

runner record

Controls video recording on a browser, mobile, or Windows runner. Run a flow first, so the runner has a screen to record. Examples:
Subcommands:
  • start — start recording across runs, and pause automatic recording until you stop it. Returns the recording’s id. --recording-id <uuid> sets the id; reuse it when you retry a start.
  • stop <recording-id> — stop that recording and publish it. Exits 1 if the published recording failed.
  • status — show the active recording and the automatic recording setting.
  • auto <on|off> — turn automatic recording of later full runs on or off.

runner list-recordings

Lists one page of a runner’s published video recordings, including after the runner terminates. Each entry has its status, its run IDs, a url for its QA Wolf page, and a videoUrl when video is available. The url persists, and the videoUrl expires. Pages come in storage order, not newest first. Terminating a runner clears the current directory’s default, so pass --runner to read an ended runner’s recordings. Examples:
Options:
  • --recording-id <uuid> — look up one recording. An empty result means it isn’t published or doesn’t exist.
  • --page-token <token> — continue from the nextPageToken the previous page returned.

agent

Asks the QA Wolf AI for work and follows what it does. Requires authentication.

agent send <message>

Asks the QA Wolf AI to do a piece of work, such as covering a journey or fixing a broken flow. Opens a new session unless --session names one, and prints the session’s ID and URL. Remembers the session, so a later agent get in the same directory needs no ID. With --follow, the command prints each reply as it arrives and exits when the session settles: 0 when it completed, 1 when it failed or was cancelled, and 6 at --timeout. In --json or --agent mode, a follow ends with one line holding the whole session, the same object a plain agent get prints. When a followed session asks a question, an interactive terminal prompts you for the answer and keeps following. Anywhere else, such as a CI job or --json mode, the CLI prints the question and the command that answers it, then exits 0. Examples:
Options:
  • --follow — report what the session says until it settles, and answer its questions as they come. Default: false.
  • --session <id> — continue this session instead of opening a new one, to answer a question or add context to work already running.
  • --environment-id <env> — the id or alias of the environment to work in. Defaults to QAWOLF_ENVIRONMENT. Ignored with --session, because a session keeps the environment it opened in.
  • --file-paths <path...> — up to 20 team-storage paths of files the request is about, from qawolf file requestUpload. The AI reads them from storage, not from the message.
  • --builds <ids...> — builds the request is about, from qawolf build upload or qawolf build create, one per app and platform. The session’s runs install them in place of the environment’s builds of the same app and platform. Put the message before this flag.
  • --workspace-id <id> — the workspace to work in. Required with an organization or user API key.
  • --timeout <seconds> — stop following after this long. Default: 1800.

agent get [session]

Reads what the QA Wolf AI has said in a session, and whether it’s still working. Targets the session you name, then QAWOLF_SESSION_ID, then the session agent send last sent to from the current directory. With --follow, it reports and exits the way agent send --follow does. Examples:
Options:
  • --follow — report what the session says until it settles, and answer its questions as they come. Default: false.
  • --session <id> — the session to read, in place of the [session] argument.
  • --sessions <ids...> — follow several sessions in one process, and return the first completion, failure, cancellation, or question. Requires --follow.
  • --workspace-id <id> — the workspace an answer given during --follow goes to. Required with an organization or user API key.
  • --timeout <seconds> — stop following after this long. Default: 1800.

run

Triggers and manages runs on the QA Wolf platform. Unlike the local execution commands, run does not execute flows on your machine and requires authentication. The other run commands are listed under Public API commands.

run create

Creates a run on the QA Wolf platform for the flows and tags you select. Pass --flow-ids, --tag-names, or both. Examples:
Options:
  • --environment-id <env> — required. The id or alias of the environment to run. Defaults to QAWOLF_ENVIRONMENT. See where to find it.
  • --flow-ids <flow_id>... — the flows to run, by ID.
  • --tag-names <tag>... — run the flows carrying these tags.
  • --builds <build_id>... — up to 20 builds to install in this run only, in place of the environment’s latest build of the same app and platform. See Test a build in one run.
  • --environment-variables <KEY=VALUE...> — environment variables for this run only, on top of the environment’s own.
  • --ignore-rules — ignore the workspace’s sequencing rules. By default they’re honored: the flows your selection depends on are added to the run, and flows run in the order the rules require.
  • --repository <owner/name> — the repository to associate with the run, such as acme/web.
  • --pull-request-number <number> — with --repository, the pull request to associate with the run.
  • --workspace-id <id> — the workspace the environment belongs to, which an alias resolves in.

attempt

Investigates a finished run attempt from its recorded trace and execution log. Requires authentication. Attempt IDs come from qawolf run get.

attempt get

Gets a finished run attempt: its run and flow status, its place among that flow’s attempts in the run, the checks that failed in it, and signed links to its logs, trace, and video when they were captured. Example:
Options:
  • --attempt-id <id> — required. The attempt to get.

attempt investigate

Summarizes the evidence for one finished attempt. The summary carries evidence IDs that attempt inspect reads in full. Example:
Options:
  • --attempt-id <id> — required. The attempt to summarize.

attempt inspect

Reads one kind of evidence for a finished attempt. Pass exactly one of --action, --timeline, --network, --request, --snapshot, --screenshot, --console, or --log. Examples:
Options:
  • --attempt-id <id> — required. The attempt to inspect.
  • --action <id> — one action, by evidence ID.
  • --timeline — the action timeline.
  • --network — network requests.
  • --request <id> — one network request, by evidence ID.
  • --snapshot <id> — one page snapshot, by evidence ID.
  • --screenshot <id> — one screenshot, by evidence ID. Requires --output-file.
  • --console — browser console entries.
  • --log — execution log entries.
  • --evidence-id <id> — with --console or --log, return only this record.
  • --limit <number> — with --timeline, --network, --console, or --log, the most entries to return, up to 100. --console returns the earliest entries, and the others return the most recent. Default: 20.
  • --start-time-ms <number>, --end-time-ms <number> — with --network or --console, the trace time window, in milliseconds.
  • --start-timestamp <iso>, --end-timestamp <iso> — with --log, the time window, as ISO 8601 timestamps.
  • --source <source> — with --log, the log source: qawolfTraceCollection or serverConsole.
  • --method <method>, --status <code>, --url-contains <text> — with --network, filter by HTTP method, HTTP status, or URL substring.
  • --format <format> — text or html. html works only with --snapshot. Default: text.
  • --output-file <path> — write the screenshot, or the HTML of a --format html snapshot, to this file. Refuses to overwrite an existing file.

build

Manages app builds. See Upload builds. The other build commands are listed under Public API commands.

build upload <file>

Uploads an .apk, .aab, or .ipa of up to 1 GB and creates a build from it. Requires CLI 2.8.0 or later. Examples:
Options:
  • --environment-id <id> — put the build on this existing environment. Its runs install the build until a newer build of the same app and platform arrives.
  • --environment-name <name> — put the build on the environment with this alias or name. Creates the environment when none matches.
  • --environment-ephemeral — with --environment-name, create an ephemeral environment when the name creates one.
  • --environment-base-ephemeral-environment <name> — with --environment-ephemeral, the environment a created ephemeral environment copies from.
  • --branch <branch> — the branch the build came from.
  • --commit-sha <sha> — the commit the build came from.
  • --workspace-id <id> — the workspace to upload into. Required with an organization or user API key.
Without an environment option, only the runs created with the build install it.

help

Displays help for a command, or for the whole CLI when you name none. qawolf <command> --help does the same. Examples:

help ref [command...]

Prints the full help of a command and of every command under it, as Markdown. Omit the command to print the whole CLI. help reference is an alias. qawolf help ref runner prints the runner guide and the help of every runner command. Examples:

Public API commands

The CLI generates one command for each QA Wolf public API operation, named qawolf <group> <operation>. Their options come from the operation’s input, so they change with the API. Run qawolf <group> <operation> --help for one command’s options, or qawolf help ref <group> for a whole group. Every one requires authentication. On every command that takes --environment-id, it defaults to QAWOLF_ENVIRONMENT. An option that takes JSON also accepts @<path> to read the JSON from a file, or - to read it from stdin. Examples:
Last modified on November 9, 2026