@clipboard-health/scout-cli

scout — the session orchestrator for Scout. Drive a real browser, record capture-enabled QA sessions (Playwright trace, video, network HAR, console, per-step screenshots), and render a self-contained report.html you can open, commit, or browse in a local UI.

Scout is built for AI agents and developers who need verifiable, reproducible browser QA. Every run captures a trace, a video, a network log, console output, and per-step screenshots — and decodes back to a reproducible Playwright script — with no instrumentation of your app. Scripts are plain async JavaScript run in a sandboxed QuickJS runtime; a background daemon (Playwright + sandbox) starts automatically when needed.

How it works

You drive the daemon through a four-step session lifecycle:

| Step | Command | Result | | --- | --- | --- | | 1. start | scout session start --name "checkout" | prints a session id | | 2. run | scout run step.js --session <id> --step open | one script per step | | 3. end | scout session end <id> | writes report.html | | 4. view | scout ui | browse every session |

Install

npm i -g @clipboard-health/scout-cli     # adds the `scout` command
scout install              # one-time: download Chromium + runtime (~150 MB) into ~/.scout

Prefer not to install globally? Prefix anything with npx:

npx @clipboard-health/scout-cli install

Or set everything up interactively with the guided wizard — npm create scout.

Quickstart

# 1. start a capture-enabled session (prints an id)
id=$(scout session start --name "checkout")

# 2. run scripts as ordered steps — one script per step (open → act → assert)
scout run ./open.js   --session "$id" --step "open"
scout run ./submit.js --session "$id" --step "submit"

# inline scripts work too (read from stdin):
echo 'const p = await browser.getPage("home");
await p.goto("https://example.com");
console.log(await p.title());' | scout run --session "$id" --step "home"

# 3. finish — collects artifacts and renders the report
scout session end "$id"            # -> ~/.scout/sessions/<id>/report.html

# 4. browse, search, and replay every session in a local viewer
scout ui

Each --step is one entry in the report, with its own trace group and one auto-captured screenshot (taken from the last page opened during that step). So use one primary named page per step, and reuse the same page name across steps to "click through" like a user — named pages persist across steps within a session.

Commands

| Command | What it does | | --- | --- | | scout init | One-shot setup: install the runtime, then print next steps. The friendlier wizard is npm create scout. | | scout install | Install the embedded runtime (Chromium + Playwright + QuickJS) into ~/.scout. | | scout session start | Start a capture-enabled session; prints its id. Toggle capture with --no-trace / --no-video / --no-har / --no-console; --headless for unattended runs. | | scout run [FILE] | Run a script (a file, or stdin if omitted) as one step. Requires --session <id>; label it with --step <name>; bound it with --timeout <seconds>. | | scout session end <id> | Stop recording, collect artifacts, render report.html + results.json. --stop-daemon shuts the daemon down afterward if nothing else needs it. | | scout session abort <id> | Best-effort teardown of a session — salvage a wedged run from whatever artifacts survived. | | scout session list | List recorded sessions (table; --json for machine output). | | scout status [--session <id>] | Daemon status, or one session's status. | | scout ui | Launch the local session viewer. Options: --dir <path>, --port, --host, --no-open. | | scout stop | Stop the background daemon and every browser/session it's running (alias: scout daemon stop). |

Global flags: --json (machine-readable output on stdout), -v / --verbose (more logging on stderr). Run scout --help or scout <command> --help for the full reference.

Lifecycle tip: scout stop aborts any live session and skips its report.html. For a clean report, always scout session end <id> first, then scout stop.

Writing scripts

Scripts are plain async JavaScript in a QuickJS sandbox with a Playwright-like API — no require, process, fs, or fetch; just a pre-connected browser, console, and a few file helpers. Top-level await works.

const page = await browser.getPage("home");          // named, persistent page
await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
console.log(await page.title());

await page.locator("text=Sign in").click();
await saveScreenshot(await page.screenshot(), "signed-in.png");   // saveScreenshot(buffer, name)

• Pages — browser.getPage(name), browser.newPage(), browser.listPages(), browser.closePage(name). Pages are full Playwright Pages (goto, click, fill, locator, evaluate, getByRole, waitForSelector, …).
• Files (sandboxed to ~/.scout/tmp/) — saveScreenshot(buffer, name), writeFile(name, data), readFile(name) to pass values between steps.

The full reference is built into this CLI — run scout --help or scout run --help (the engine's scout-browser --help documents the same API), or read the scout-scripting reference.

Artifacts

Everything for a run lands under ~/.scout/sessions/<id>/:

session.json   session metadata + per-step record
results.json   decoded results (steps, summary, artifact paths)
report.html    self-contained report — open it anywhere, commit it, share it
trace.zip      Playwright trace (DOM snapshots + actions, one group per step)

…plus the WebM video, the network HAR, the console log, and one screenshot per step.

Use it from an AI agent

Scout ships skills, subagents, and /scout:* slash commands for Claude Code, Cursor, and Codex, so an agent can plan and record QA for you:

# Claude Code: /plugin marketplace add ClipboardHealth/scout  then  /plugin install scout@scout-marketplace

Related packages

• @clipboard-health/scout-browser — the engine for quick one-off automation (no recording, no report).
• @clipboard-health/scout-ui — the scout-viewer session browser.
• create-scout — npm create scout guided setup.

MIT · source