These are the commands most workflows use. Run qawolf help to list all of them.
auth
Manages authentication with the QA Wolf platform. The CLI reads credentials from the QAWOLF_API_KEY environment variable first, then the system keychain, then a config file fallback.
auth login
Prompts for an API key, validates it against the platform, and stores it locally. Requires an interactive terminal — in non-interactive contexts, set QAWOLF_API_KEY directly.
auth logout
Removes stored credentials. This command cannot remove credentials set via the QAWOLF_API_KEY environment variable.
auth whoami
Displays the authenticated workspace name, ID, optional slug, and the credential source.
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.
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.--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_id> — environment ID. When set, the CLI pulls missing flows before the run. See where to find it.
Exit codes: 0 when all flows pass, 1 when one or more flows fail, 2 for invalid arguments or an unrecognized flow target. See Exit codes.
flows list [pattern]
Lists flows matching [pattern]. By default, lists local flows; with --remote, lists flows from the QA Wolf platform.
Options:
--remote — list flows from the QA Wolf platform instead of the local project. Default: false.
flows pull
Downloads an environment’s flows into the local .qawolf/<env_id>/ cache.
Options:
--env <env_id> — required. The environment ID to pull from. 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.
install browsers [pattern]
Installs the Playwright browsers used by the project’s web flows.
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.
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, creates one with "type": "module", the @qawolf/flows dependency, and a test:e2e script. When one already exists, only adds the test:e2e script, after a prompt.
Options:
--yes — overwrite existing files 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.
Options:
--all — run every platform check, including platforms the project does not use. Default: false.
runner
Launches and drives a browser, an Android device, or an iOS device 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 and actions launch a new browser runner, which bills while it’s up, and say so on stderr.
runner launch
Launches a runner and stores it as the current directory’s default.
Options:
--id <id> — the runner’s id, chosen by you. 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, or ios. Default: playwright.
runner list
Lists the runners running in your workspace.
Options:
--here — list only the runners launched from the current directory. Default: false.
runner terminate
Ends a runner and the pod it runs on.
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 or iOS runner, the first run starts the device session, so run a flow before you take screenshots or act on it. The flow’s target has to match what the runner runs.
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.--env-id <env> — the id or alias of the environment whose variables the run gets. Defaults to QAWOLF_ENVIRONMENT.--env-file <path> — a dotenv file whose variables the run gets. Pass this or --env-id, not both.--lines <start-end> — run only these lines against the runner’s current page, instead of the whole flow.--lines-file <path> — the file --lines refers to, such as a page object. Defaults to <flowFile>.--timeout <seconds> — stop following after this long. Default: 3600.
runner screenshot
Saves a JPEG of the runner’s screen.
Options:
--out <path> — the file to write. - writes the image to stdout. 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.
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. 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.--button <button> — click: left, right, wheel, back, or forward.--keys <keys...> — keypress: modifiers and the key, for example Control a.--url <url> — navigate: the URL to go to.--screenshot <path> — also save a screenshot taken after the action.
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.
Options:
--screenshot <path> — save a screenshot taken after the last action.--continue-on-failure — carry on past an action that did not take effect. Default: false.
runner inspect
Reads one thing off the runner’s live page or Appium session and prints it to stdout.
Subcommands:
element-html — browser only. The HTML of the first element --selector matches.page-html — browser only. The page’s HTML, simplified.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.elements — mobile only. The elements at --x and --y, carrying --text, or matching --selector.
runner record
Controls video recording on a browser runner.
Subcommands:
start — start recording across runs. Returns the recording’s id.stop <recording-id> — stop that recording and publish it.status — show the active recording and the automatic recording setting.auto <on|off> — turn automatic recording of later full runs on or off.
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.
run create
Creates a run on the QA Wolf platform.
Options:
--environment-id <env> — the id or alias of the environment to run. See where to find it.--environment-variables <KEY=VALUE...> — environment variables to set for the run.--flow-ids <flow_id>... — limit the run to specific flow IDs.--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.
Last modified on October 15, 2026
