Quickstart: CLI and local agent

QualityMax has two terminal tools: qmax, the local execution agent for scripted and CI-friendly workflows, and qmax-code, an interactive testing agent. This quickstart uses both and ends at a run you can inspect.

1. Install and authenticate qmax

Install the public qmax release on macOS or Linux, then authenticate it:

curl -fsSL https://raw.githubusercontent.com/Quality-Max/qmax-local-agent/main/install.sh | bash
qmax login

The installer detects your operating system and architecture and downloads the matching binary from the public qmax releases. Windows users can download qmax-windows-amd64.exe from the same page. You can audit the installer source before running it.

qmax login opens a browser so you can authenticate without placing credentials in a command or workspace file. Confirm the installation with:

qmax status

2. Run the local agent behind a firewall

The local agent polls QualityMax for work; it does not need an inbound listener. On a managed network, allow the machine to make outbound HTTPS connections to QualityMax.

In the web app, open Agents, choose Install Agent, and copy the generated registration command. It contains a per-user registration secret, so run it only on the intended machine and do not paste it into tickets, documentation, or shell history shared with other users. The command has this shape:

qmax run --cloud-url https://app.qualitymax.io --registration-secret <generated-secret>

Leave that process running. In the QualityMax web app, select Use Local Agent for the execution and choose the agent that appears online. Generate or select a small Playwright script, then start the execution from the project. The browser work runs on the machine hosting qmax.

3. Run a script and wait for the result

For a known script identifier, the CLI can start one execution and wait for its terminal state:

qmax test run --script-id <script-id> --wait

On success, qmax reports Status: PASSED and reports captured screenshots or video when they are available. If you started a run without --wait, check it later with:

qmax test status --execution-id <execution-id>

Open the execution in QualityMax to inspect its logs and captured artifacts. Open the trace when the run includes one.

4. Use qmax-code for the interactive path

Install the public qmax-code release for your operating system, authenticate, then launch it:

curl -sL https://qualitymax.io/static/install-qmax-code.txt | bash
qmax-code login
qmax-code

Complete its browser sign-in, then ask it to create a narrow test and run it. For example:

Create a Playwright test for the public search journey in my selected project. Run the test,
wait for the result, and show me the execution artifacts and trace if available.

Use the returned execution to confirm a passing result and inspect its evidence. qmax-code is best for this conversational exploration; keep qmax running when you need the execution to stay inside a network that permits only outbound HTTPS.

For a coding-agent workflow that does not require the terminal tools, see the MCP quickstart.