Getting Started

Tip

Verfix is local-first. verfix run executes entirely in a single Node.js process on your machine — no Docker, no queue, no cloud account. The one-time Docker server runtime is opt-in (--server) and only needed for the future hosted CI product — see Self-Hosting.

Prerequisites

• Node.js 20+ — node --version to check. That’s the whole list.
• The first run downloads Chromium (~130MB, one-time, cached in ~/.cache/ms-playwright).

---

Install the CLI

npm install -g verfix

Or use it without installing globally:

npx verfix init

Verify the installation:

verfix --version

---

Init your project

Run this inside your web app’s directory:

cd your-react-app
npx verfix init

The interactive wizard will:

1. Detect your app’s base URL (e.g. http://localhost:3000)
2. Ask which mode to use — default strict (fully deterministic, no AI key needed)
3. Ask for an AI key only if you picked assisted/exploratory
4. Make sure Chromium is available (downloads it once if missing)
5. Write an empty verfix.config.json (flows: []) in your project root
6. Generate or update AGENTS.md (plus a .verfix/INSTRUCTIONS.md reference file) so coding agents know how to use Verfix

Tip

There’s no flow-scaffolding step and no preset flow library — verfix init doesn’t know your app’s routes or components. It hands the agent an empty flow library and the full reference at .verfix/INSTRUCTIONS.md, and the agent writes the first real flow by reading your source. See Config-First Verification and the example below.

Tip

For non-interactive environments (CI/CD or AI agents), use verfix init --yes. Strict mode needs zero credentials — an AI key is only required for assisted/exploratory modes. See the CLI Reference for all flags and environment variables.

There is no runtime to start and nothing to keep running — verfix run executes the browser engine in-process and exits when it’s done.

---

Write your first flow

verfix.config.json starts with an empty flows: [] — Verfix doesn’t know your app’s routes or components, so it doesn’t guess at them. This is normally the agent’s job (read the source, find the real selector, write the flow — see Config-First Verification), but for a first run by hand, add one directly:

{
  "baseUrl": "http://localhost:3000",
  "mode": "strict",
  "flows": [
    {
      "id": "login",
      "steps": [
        { "action": "navigate", "url": "/login" },
        { "action": "type", "selector": "[data-testid=email]", "value": "test@example.com" },
        { "action": "type", "selector": "[data-testid=password]", "value": "password123" },
        { "action": "click", "selector": "[data-testid=submit]" }
      ],
      "assertions": [
        { "type": "url_contains", "value": "/dashboard" },
        { "type": "no_console_errors" }
      ]
    }
  ]
}

Run it

verfix run --flow login --output json

Example output on pass:

{
  "passed": true,
  "failures": [],
  "timeline_url": null,
  "trace_path": ".verfix/runs/exec_abc123_trace.zip",
  "show_command": "verfix show exec_abc123",
  "duration_ms": 3120,
  "retry_count": 0,
  "exit_code": 0,
  "execution_id": "exec_abc123"
}

Example output on failure:

{
  "passed": false,
  "failures": [
    {
      "type": "selector_not_found",
      "flow": "login",
      "assertion": "selector_visible",
      "selector": "[data-testid=submit]",
      "detail": "Selector not found after 15000ms",
      "fix_hint": "Selector \"[data-testid=submit]\" not found in DOM. Add a stable data-testid or update the selector."
    }
  ],
  "timeline_url": null,
  "trace_path": ".verfix/runs/exec_xyz789_trace.zip",
  "show_command": "verfix show exec_xyz789",
  "exit_code": 1,
  "execution_id": "exec_xyz789"
}

The CLI exits 0 on pass, 1 on a verification failure, and 2 on a setup error (bad config, missing flow, etc.) — predictable exit codes for CI and agent loops.

---

Inspect the recorded trace

Every run persists a full Playwright trace (screenshots, network requests, console output) plus a JSON summary under .verfix/runs/ (newest 20 runs kept). Open the newest one:

verfix show

Or a specific run by its execution id:

verfix show exec_abc123

Print a run’s console log or network requests straight to the terminal instead of opening the trace viewer:

verfix show --console
verfix show exec_abc123 --network --output json

When a selector fails, dry-run replacement selectors against that run’s saved DOM snapshot in about a second — instead of paying for a full re-run per guess:

verfix probe --selector "[data-testid=submit]" --text "Welcome back"

---

List all flows

verfix flows

Run all flows at once:

verfix run --output json

---

Check your setup

verfix doctor

Checks Node version, verfix.config.json validity, AGENTS.md, Chromium install status, and app reachability. Docker is only checked (and only matters) if you’re using --server.

Validate your config without running anything:

verfix validate

---

Next steps

• CLI Reference — all commands and flags
• Config Reference — every field in verfix.config.json
• Config-First Verification — why agents should fix flows, not source
• Agent Integration — wiring Verfix into agent workflows
• Execution Modes — when to use strict vs. assisted vs. exploratory