Prowl for Agents

Prowl is CLI-first and agent-native by design. A single CLI command can capture an entire hunt run. Structured JSON output, deterministic exit codes, and minimal context overhead give AI agents what they need to discover, run, and report on browser tests without wrangling automation APIs directly.

Made for agents, controlled by humans. You write the hunts, review the results, and set the guardrails. Agents handle the execution loop — discovering what to test, running the hunts, and reporting structured results back to your workflow.

Jump to the Library API for programmatic Node.js integration, the MCP Server to connect an agent without shell access, or Using Hub Templates for pre-built community hunt templates.

Quickstart in 60 Seconds

Get an agent running hunts in four commands:

# 1. Install
npm install -g prowl-tools

# 2. Initialize a project
prowl init

# 3. Run a hunt with structured output
prowl run smoke-test --json

{
  "hunt": "smoke-test",
  "status": "passed",
  "steps": 4,
  "duration": "1.2s"
}

# 4. Branch on the result
prowl run smoke-test --json && echo "✅ Passed" || echo "❌ Failed"

Exit codes make branching simple: 0 = passed, 1 = failed, 2 = no hunts found. Run all hunts at once with prowl ci --json.

tip

That's the full loop — install, run, branch. The sections below cover the details: workflow patterns, the Node.js library API, CI integration, and Hub templates.

Why CLI-First

Prowl is designed around the same interface agents already know: the shell. A single CLI command replaces multi-step tool orchestration, and structured output means agents spend less time parsing and more time acting.

Minimal Context Overhead

• No schema preamble. The CLI is invisible to the agent's context until invoked — no manifest or tool definitions sitting in every turn.
• Declarative, not imperative. A 10-step hunt is a single prowl run call — not 10+ individual tool invocations the agent has to reason through.
• Pay-per-use. Tokens are only spent when the agent actually calls a command and reads its output.

Exit Codes Enable Branching

Agents don't need to parse response bodies to decide what to do next. A zero exit code means pass, non-zero means fail — standard shell semantics that every agent framework already understands.

prowl ci --json && echo "All hunts passed" || echo "Failures detected"

tip

Prowl is agent-ready out of the box. Install, run, parse — structured JSON output and deterministic exit codes from the first command.

Agent Workflow: Discover, Run, Report

Every agent integration follows the same three-step pattern — each step is a single CLI call with structured output:

1. Discover

List available hunts and their metadata:

prowl list --json

[
  { "name": "smoke-test", "description": "Validates homepage loads", "tags": ["smoke"] },
  { "name": "login-flow", "description": "Email/password login", "tags": ["auth", "critical"] },
  { "name": "checkout-flow", "description": "E-commerce checkout", "tags": ["e2e"] }
]

Agents can filter by tags to select the right hunts for the context (e.g., run only smoke hunts on every PR, run e2e hunts nightly).

2. Run

Execute a single hunt or all hunts:

# Single hunt
prowl run smoke-test --json

# All hunts (CI mode)
prowl ci --json

3. Report

Parse the structured JSON output and check exit codes:

Exit Code	Meaning
0	All hunts passed
1	One or more hunts failed
2	No hunts found or all skipped

CLI Integration (--json flags)

prowl run <hunt> --json

Returns a single hunt result:

{
  "status": "pass",
  "exitCode": 0,
  "startedAt": "2026-02-16T17:15:12.481Z",
  "hunt": "smoke-test",
  "targetUrl": "http://localhost:3000",
  "durationMs": 220,
  "steps": [
    { "type": "navigate", "status": "pass", "durationMs": 120 },
    { "type": "wait", "status": "pass", "durationMs": 85, "selector": "text=\"Welcome\"" },
    { "type": "assert", "status": "pass", "durationMs": 15, "value": "visible:Sign In" }
  ],
  "assertions": [
    { "type": "noConsoleErrors", "value": true, "status": "pass" },
    { "type": "noNetworkErrors", "value": true, "status": "pass" }
  ],
  "artifacts": {
    "summary": "summary.md",
    "screenshots": ["screenshots/final.png"],
    "console": "console.log"
  }
}

prowl ci --json

Returns a combined result for all hunts:

{
  "status": "fail",
  "startedAt": "2026-02-16T17:15:12.481Z",
  "durationMs": 4870,
  "totalHunts": 3,
  "passed": 2,
  "failed": 1,
  "skipped": 0,
  "hunts": [
    { "hunt": "smoke-test", "status": "pass", "durationMs": 220, "runDir": "/path/to/.prowl/runs/2026-02-16_17-15-15" },
    { "hunt": "login-flow", "status": "pass", "durationMs": 1450, "runDir": "/path/to/.prowl/runs/2026-02-16_17-15-20" },
    { "hunt": "checkout-flow", "status": "fail", "durationMs": 3200, "error": "Assertion failed: visible \"Order Confirmed\"" }
  ]
}

JUnit XML

For CI systems that consume JUnit XML (GitHub Actions, GitLab CI, Jenkins, CircleCI), pass --junit:

prowl ci --junit

Each hunt run directory gets its own junit.xml (for example .prowl/runs/<timestamp>/junit.xml).
In CI mode, prowl ci also writes a combined summary JSON file at .prowl/runs/ci-<timestamp>/ci-result.json.

prowl history <hunt> --json

Every prowl run and prowl ci appends to .prowl/history.json. Agents can read past runs to detect flakes or track duration trends:

prowl history smoke-test --json --limit 50

[
  { "hunt": "smoke-test", "status": "pass", "durationMs": 220, "startedAt": "2026-05-28T17:15:12.481Z", "runDir": ".prowl/runs/2026-05-28_17-15-12-481" },
  { "hunt": "smoke-test", "status": "fail", "durationMs": 1840, "startedAt": "2026-05-28T09:02:55.001Z", "runDir": ".prowl/runs/2026-05-28_09-02-55-001" }
]

Retention is configurable via history.maxRuns — see Configuration.

Connect Over MCP

For agents that support the Model Context Protocol, Prowl ships an MCP server that exposes QA as named tools (list_hunts, run_hunt, run_suite, list_projects) over stdio — no shell access required. The agent connects once and drives runs through tool calls, with run_suite optionally logging failures straight to your backlog.

See the MCP Server guide for client configuration, the tool reference, automated bug-logging, and multi-project setup.

Library API (Node.js)

For deeper integration, import Prowl as a library:

import { runHunt, loadConfig, listHunts, loadHunt } from "prowl-tools";

Core Functions

Function	Description
runHunt({ huntName, ...options })	Run a hunt programmatically and get a typed RunResult
runSuite(options?)	Run an entire suite (the engine behind prowl ci); returns aggregated CiResult
updateBacklogFromSuite(suiteResult, options?)	Log a suite's failures as deduplicated bug tickets in docs/backlog.md
readHistory(configDir) / readHuntHistory(configDir, hunt)	Read run history from .prowl/history.json
loadConfig(configPath?)	Load and validate config, returning { config, configPath, configDir }
loadHunt(huntName, configDir)	Load and parse a single hunt file from <configDir>/hunts/
listHunts(configDir)	List available hunt names from <configDir>/hunts/

Schemas

Prowl exports Zod schemas for validation:

import { huntSchema, configSchema, stepSchema } from "prowl-tools";

// Validate a hunt file an agent generated
const result = huntSchema.safeParse(agentGeneratedHunt);
if (!result.success) {
  console.error(result.error.issues);
}

Variable Interpolation

import { loadConfig, loadHunt, interpolateHunt } from "prowl-tools";

const { configDir } = loadConfig();
const hunt = loadHunt("login-flow", configDir);
const { hunt: interpolated } = interpolateHunt(hunt, {
  ...process.env,
  EMAIL: "test@example.com",
  PASSWORD: process.env.TEST_PASSWORD ?? "",
});

Suite Runner and Automated Bug-Logging

runSuite() runs an entire hunt suite programmatically — the same engine behind prowl ci — and updateBacklogFromSuite() turns its failures into deduplicated bug tickets. This is the non-CLI path to the same automated bug-logging the MCP run_suite tool performs.

import { runSuite, updateBacklogFromSuite } from "prowl-tools";

const suite = await runSuite({
  includeTags: ["smoke"],
  parallel: 4,
});

console.log(`${suite.result.passed}/${suite.result.totalHunts} passed`);

// Log failures to docs/backlog.md (and detect regressions against docs/resolved.md)
const summary = updateBacklogFromSuite(suite, { projectRoot: process.cwd() });

console.log("New tickets:", summary.created);     // e.g. ["QA-014"]
console.log("Regressions:", summary.regressions); // e.g. ["QA-015"]
console.log("Already open:", summary.skipped);    // left untouched

runSuite(options?) returns Promise<{ result: CiResult; resultPath: string | null }>. Key options:

Option	Type	Description
configPath	string	Path to config (defaults to discovery from cwd)
urlOverride	string	Override target.url
includeTags / excludeTags	string[]	Tag filters
parallel	number	Number of concurrent workers
junit	boolean	Emit junit.xml per run
headed, slowMo, trace, browser, channel, viewport	—	Same semantics as the matching CLI flags
hooks	RunSuiteHooks	Progress callbacks: onHuntStart, onStep, onHuntSuccess, onHuntFailure, onHuntSkipped

updateBacklogFromSuite(suiteResult, options?) returns a BugLogSummary — { created, regressions, skipped, backlogPath }. A failure is fingerprinted by hunt + failing step (type/selector) + normalized error, so new failures get a QA-NNN ticket under a ## QA Findings (automated) section, already-open failures are skipped, and failures matching a resolved ticket are logged as regressions. Options:

Option	Type	Default	Description
projectRoot	string	process.cwd()	Project root containing docs/
backlogPath	string	<projectRoot>/docs/backlog.md	Override the backlog path
resolvedPath	string	<projectRoot>/docs/resolved.md	Override the resolved-tickets path
date	string	today (YYYY-MM-DD)	Date stamp for new tickets

Run History

readHistory() and readHuntHistory() read the .prowl/history.json log written by every run and ci:

import { loadConfig, readHistory, readHuntHistory } from "prowl-tools";

const { configDir } = loadConfig();

const all = readHistory(configDir);                     // { entries: HistoryEntry[] }
const smoke = readHuntHistory(configDir, "smoke-test"); // HistoryEntry[]

const failRate = smoke.filter((e) => e.status === "fail").length / smoke.length;

HistoryEntry is { hunt: string; status: "pass" | "fail"; durationMs: number; startedAt: string; runDir?: string }. Retention is capped per hunt by history.maxRuns — see Configuration.

Using Hub Templates

The Prowl Community Hub is a collection of pre-built hunt templates — common patterns like login flows, CRUD cycles, checkout funnels, and onboarding wizards.

note

The prowl hub CLI is coming in a future release. In the meantime, browse templates on the Prowl Community Hub or use the Hub API for programmatic access.

Manual Workflow

1. Browse templates in the Prowl Community Hub.
2. Copy the template hunt file into your local .prowl/hunts/ directory.
3. Customize {{VAR}} placeholders for your environment.
4. Execute the hunt with prowl run <hunt-name> --json.

Example hunt after copying and customizing:

name: login-flow
description: Email/password login with error handling
baseUrl: "{{BASE_URL}}"
steps:
  - navigate: "{{BASE_URL}}/login"
  - fill:
      selector: "[name='email']"
      value: "{{EMAIL}}"
  - fill:
      selector: "[name='password']"
      value: "{{PASSWORD}}"
  - click: "button[type='submit']"
  - wait: "Welcome"

Variables are resolved from your config, environment, or CLI flags. See Variables for interpolation precedence.

API Access

Agents can skip the manual workflow entirely. The Hub API exposes REST endpoints for searching, filtering, and downloading templates programmatically — so an agent can discover the right template, fetch it, and run it without human intervention. See the Hub API reference for endpoints, schemas, and a full workflow example.

Library API for Templates

Use the library API to customize and run downloaded templates programmatically:

import { loadConfig, loadHunt, interpolateHunt, runHunt } from "prowl-tools";

const { configPath, configDir } = loadConfig();

// Load the template
const hunt = loadHunt("login-flow", configDir);

// Preview interpolation with custom variables
const { hunt: preview } = interpolateHunt(hunt, {
  ...process.env,
  BASE_URL: "https://staging.example.com",
  EMAIL: "test@example.com",
  PASSWORD: process.env.TEST_PASSWORD ?? "",
});

console.log(preview.steps[0]);

// runHunt reads vars from process.env
process.env.BASE_URL = "https://staging.example.com";
process.env.EMAIL = "test@example.com";
process.env.PASSWORD = process.env.TEST_PASSWORD ?? "";

const { result } = await runHunt({
  huntName: "login-flow",
  configPath,
});

if (result.status === "pass") {
  console.log(`Login flow passed in ${result.durationMs}ms`);
} else {
  console.error("Login flow failed:", result.steps.filter((s) => s.status === "fail"));
}

note

Browse all templates and contribute your own at the Prowl Community Hub.

Community Hub

Pre-built hunt templates for common test patterns

Configuration

Browser settings, timeouts, guardrails, and artifacts

Step Types

All 28 step types available in hunts

Troubleshooting

CLI reference, artifacts, and common issues