Install and setup

One command installs the binary and provisions its own pinned Playwright runtime, separate from anything already on your machine.

Prerequisites

Node.js 18 or newer, with npm
Python 3.9 or newer, with venv

These are needed to provision the runtime. They are not needed to write tests — the agent installs its own Playwright and Chromium and does not use your global packages.

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/install.sh | sh

The installer places the binary in /usr/local/bin/ so it is on everyone's PATH, then runs qaclan setup --runtime-only to build the runtime. Supported: Linux amd64 and macOS arm64.

Windows

Download the build that matches your CPU:

Intel or AMD 64-bit — qaclan-windows-amd64.exe
ARM64, such as a Surface Pro X or a Copilot+ PC — qaclan-windows-arm64.exe

Then, in PowerShell:

.\qaclan-windows-amd64.exe setup

With no flags, setup does the full bootstrap: it copies the binary to %USERPROFILE%\.qaclan\bin\, adds that to your user PATH, and provisions the runtime. Restart PowerShell when it finishes.

SmartScreen warning

Windows may warn that the binary is from an unknown publisher the first time you run it. Choose More info → Run anyway, or unblock it first with Unblock-File .\qaclan.exe.

Setup flags

qaclan setup is idempotent — re-running it is safe. A checksum sentinel skips the dependency install when the bundled dependency list has not changed.

Flag	Effect
no flags	Full bootstrap: move the binary to `~/.qaclan/bin/`, add it to PATH, install the runtime dependencies and Chromium
`--runtime-only`	Runtime dependencies only. This is what the install scripts use
`--path-only`	Binary move and PATH only, no runtime work
`--no-path`	Skip the PATH step, for a binary that is already on PATH
`--no-move`	Leave the binary where it is; add only its current directory to PATH
`--no-chromium`	Skip the Chromium download, for machines where browsers are already staged
`--force`	Re-run every step even if it appears to be done

--path-only and --runtime-only are mutually exclusive.

What lands on disk

Everything lives under ~/.qaclan/ — on Windows, %USERPROFILE%\.qaclan\.

Path	Contents
`qaclan.db`	SQLite database: projects, features, suites, runs, collections, environments
`scripts/`	Your recorded and imported test scripts, as readable files
`screenshots/`	Screenshots captured when a script fails
`config.json`	Your auth key, active project and server URL
`runtime/`	The isolated runtime: `node_modules/`, a Python `venv/`, and `browsers/` holding Chromium

Rebuilding the runtime

If the runtime gets into a bad state — a corrupted download, or a Playwright version bump — delete just that directory and rebuild it. Your database, scripts and config are untouched.

qaclan reset-runtime --yes

qaclan setup --runtime-only

Coming from a global Playwright install

You do not need to remove it. The agent resolves its own runtime first, so a globally installed Playwright will not be used for QAClan runs and cannot cause a version clash.

Uninstalling

The recommended way, which works identically on every platform:

qaclan uninstall --yes

It removes PATH entries, the installed binary, and the whole data directory.

This deletes your local data

Uninstalling removes ~/.qaclan/ entirely: the database, every recorded script, run history, environments and credentials. If you only want to rebuild the browser runtime, use qaclan reset-runtime instead. If your work is synced to the server, you can restore it later on a new machine with qaclan pull.

Standalone uninstall scripts also exist for the case where the binary itself is broken. They remove the binary and the data directory but do not clean shell history or rc files.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/uninstall.sh | sh

Windows

irm https://raw.githubusercontent.com/qaclan/agent/master/uninstall.ps1 | iex