Using KwikQA

Commands

analyze

$ npx kwikqa analyze [--report <path>] [--framework <name>] [--local] [--yes] [--capture] [--no-probe] [--no-changes] [--html [--output <path>]]

Diagnoses the failures in a Playwright, Cypress, or WebdriverIO report, or one from the other frameworks KwikQA reads. The first line of the result says what it read, such as Read a Cypress 16.2.0 run (KwikQA reporter): 8 tests, 5 failing, 1 flaky.

Option	Effect
`--report <path>`	Read this report file, or every report file in this directory, instead of looking in the default locations.
`--framework <name>`	`playwright`, `cypress`, or `webdriverio`: the framework of a JUnit report that doesn't name one. Other formats name their own.
`--local`	Build the evidence summary on your machine only. Nothing is sent, and no account is needed.
`--yes`	Approve the request preview without asking. Needed when there is no terminal, as in CI.
`--capture`	First re-run the failing tests with your project's own runner, so every failure has full evidence. Playwright runs them with full tracing. Cypress and WebdriverIO re-run the failing spec files with your config, plus KwikQA's reporter and failure capture, which records each failed attempt's DOM, command log, console, and network. It shows the exact command and asks before running it; `--yes` approves. Output goes to `.kwikqa/capture/`, and `fix` uses it until you run your tests again.
`--no-changes`	Leave recent code changes that mention the failures out of the evidence.
`--html`	Also write the failure report, `kwikqa-report.html`.
`--output <path>`	With `--html`, write the report here instead. KwikQA replaces only a file it wrote itself.
`--no-probe`	With `--capture`, skip the live probe. Otherwise, on Playwright 1.59 or later with Playwright CLI installed, KwikQA pauses up to three locator failures at the failing line and asks Playwright for locators of the closest elements.

report

$ npx kwikqa report [--run <id>] [--output <path>]

Writes the failure report of the latest analysis without analyzing again or sending anything. It rebuilds the evidence from the same test report and artifacts, and says so if they have changed since.

Option	Effect
`--run <id>`	An earlier run, by its id under `.kwikqa/runs/`.
`--output <path>`	Where to write it; the default is `kwikqa-report.html`.

fix

$ npx kwikqa fix [--report <path>] [--propose-only] [--retry]

Proposes a repair for a test-support cause, shows the diff and validation commands, and applies the patch if you approve. It needs kwikqa.config.json and an interactive terminal, because a person approves every patch. The one exception is CI: in GitHub Actions, Azure Pipelines, or GitLab CI/CD, a committed ci.fix policy lets it validate the repair on the runner and open it as a draft pull request, which a person merges: see Fix pull requests.

Option	Effect
`--report <path>`	Repair from this report.
`--propose-only`	Stop after showing the proposal. Nothing is applied.
`--retry`	After a failed validation, re-diagnose from the validation evidence and propose one revised patch. Free. In CI, the policy's `retry` decides instead.

validate

$ npx kwikqa validate

Runs the validation plan you approved with the patch, with your project's own Playwright, Cypress, or WebdriverIO. If every required check passes, the patch is kept. Otherwise it is rolled back. It sends nothing and counts nothing.

ci

$ npx kwikqa ci [--report <path>] [--framework <name>] [--local] [--no-changes] [--output <path>] [--notify on-failure|always]

For a CI job after failing tests. It analyzes the run as analyze --yes does, writes the failure report, kwikqa-report.html, and publishes a summary of the run: on GitHub Actions, the job summary and one pull-request comment; on Azure Pipelines, a build summary and one pull-request thread; on GitLab CI/CD, the job's log and one merge-request note; on Jenkins, the console log and one comment on a GitHub or GitLab pull request. On any CI system, it can also post a Slack or Teams message through your webhooks. Without a usable KwikQA token, it analyzes locally and says why. It exits with the analysis's own exit code: anything it can't publish is reported and skipped. See Running in CI.

Option	Effect
`--report`, `--framework`, `--local`	As for `analyze`.
`--no-changes`	Leave recent code changes out of the evidence.
`--output <path>`	Write the failure report here instead of `kwikqa-report.html`. KwikQA replaces only a file it wrote itself.
`--notify <when>`	When to post to Slack and Teams: `on-failure` (the default: when tests failed) or `always`.

Account commands

Command	What it does
`npx kwikqa init`	Propose and write `kwikqa.config.json`, offer to ignore `.kwikqa/`, and show the reporter setup for each framework the project uses.
`npx kwikqa login`	Sign in with GitHub's device flow.
`npx kwikqa status`	Show your plan, this month's usage, and when it resets.
`npx kwikqa upgrade [plan]`	List plans, or get a checkout link for `pro`, `team`, `byo`, or `byo-team`. Paid plans are coming soon, so for now it lists them without a checkout link. `--annual` bills yearly (two months free); `--seats <n>` sets seats on team plans (3 or more). If you already pay, it points you to Billing in the dashboard instead.
`npx kwikqa billing`	Open Paddle's customer portal to update your card or download invoices.
`npx kwikqa logout`	Revoke this machine's token and remove it.
`npx kwikqa --version`	Print the version.

Environment variables

Variable	Used for
`KWIKQA_TOKEN`	A CLI or CI token, used instead of the stored sign-in. Create one in the dashboard.
`OPENROUTER_API_KEY`	Your OpenRouter key, on the BYOK plans.
`KWIKQA_DIAGNOSIS_MODEL`, `KWIKQA_REPAIR_MODEL`	Your own model routes on the BYOK plans, as `author/model@provider`.
`PLAYWRIGHT_JSON_OUTPUT_NAME`	Where to find a Playwright report, if set.
`KWIKQA_REPORT_DIR`	Where KwikQA's Cypress and WebdriverIO reporters write, and where `analyze` looks, if set.
`GITHUB_TOKEN`	With `ci`, the token that writes the pull-request comment: on GitHub Actions the job's own, which needs `pull-requests: write`; on Jenkins one you bind, for a pull request on GitHub. With `fix` in GitHub Actions, it also opens the fix pull request, and needs `contents: write` too.
`SYSTEM_ACCESSTOKEN`	With `ci` on Azure Pipelines, the build's `System.AccessToken`, mapped in the step's `env`, which writes the pull-request thread. With `fix`, it also pushes the fix branch and opens its pull request.
`GITLAB_TOKEN`	With `ci` on GitLab CI/CD, or on Jenkins for a merge request on GitLab, the token that writes the merge-request note. With `fix` on GitLab CI/CD, it also pushes the fix branch and opens its merge request, so it needs the `api` scope and at least the Developer role.
`KWIKQA_SLACK_WEBHOOK_URL`, `KWIKQA_TEAMS_WEBHOOK_URL`	With `ci`, the Slack and Teams webhooks to post to.
`KWIKQA_CONFIG_DIR`	Where the CLI keeps its sign-in. Defaults to `~/.config/kwikqa`, or `%APPDATA%\kwikqa` on Windows.

Exit codes

Code	Meaning
`0`	Success, or an informative result such as `diagnosed` or `inconclusive`.
`1`	The repair or validation did not succeed: `repair-failed`, `validation-unavailable`, or `operation-failed`.
`2`	Usage error: an unknown option, or a command that needs a terminal.
`3`	Sign-in, plan, or usage-limit problem.