Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / cli-browser-workflows

CLI browser workflows

The browser CLI gives an engineer two ways to collect browser Evidence: passive commands inspect an existing loopback CDP browser, while capture-browser-scenario drives a declared browser flow. Both paths use the browser analysis runtime and return structured Evidence, but they have different ownership rules. CDP observation does not change the target, while a scenario owns or connects to a browser session for the request. See Browser analysis for the wider capability model and CLI evidence and runtime commands for shared result and JSON-input behavior.

Browser command families

The CLI separates attach-only inspection from controlled interaction. This boundary tells the caller whether REA observes a browser that already exists or runs actions in a scenario-defined context.

FamilyMain purposeBrowser authority
Browser contextFind targets, inspect a page, inspect its bundle, watch user navigation, discover page-declared WebMCP tools, or capture a screenshotAttaches to a loopback CDP browser and does not launch, navigate, evaluate, or close it
Browser scenarioRun a bounded sequence of actions and retain selected page state and eventsLaunches a temporary browser profile or connects to one selected CDP target; launch mode cleans up the owned browser, while connect mode restores scenario state and disconnects without closing the external browser
Browser comparisonCompare saved passive captures, scenario captures, or screenshot artifactsReads supplied JSON and does not need a live page

The command names are registered in src/cli.ts. Browser-context commands are grouped in src/…/browserCommands.ts, advanced browser commands in src/…/browserAdvancedCommands.ts, and the scenario command in src/cliBrowserScenarioCommands.ts.

Browser context commands

Each passive command receives a CDP endpoint. Commands that act on one page also receive the target ID returned by list-browser-targets. --allowed-origins is an optional list of exact HTTP(S) origins that narrows what the command can retain. Discovery and command timeout options bound browser connection work and command cleanup where the command supports them.

CommandRequired argumentsMain optionsResult
rea list-browser-targets ENDPOINTLoopback CDP HTTP endpoint or browser WebSocket URL--allowed-origins; discovery timeoutEligible page targets and their current URLs and titles
rea inspect-web-page ENDPOINT TARGET_IDEndpoint and target ID--observation-ms; origin scope; discovery and command timeouts; optional accessibility text, console text, JSON body shapes, WebSocket shapes, script sources, storage keys, and storage fingerprintsBounded page, resource, event, and selected content observations
rea analyze-web-bundle ENDPOINT TARGET_IDEndpoint and target ID--observation-ms; semantic-precision JSON; source-map fetching and limits; heap and analysis-time controls; Evidence delivery controlsStatic script and bundle findings such as chunks, routes, endpoints, and source-map evidence
rea observe-web-session ENDPOINT TARGET_IDEndpoint and target ID--observation-ms; origin scope; discovery and command timeoutsOrdered navigation and target-lifecycle events during a user-driven window
rea discover-webmcp-tools ENDPOINT TARGET_IDEndpoint and target ID--observation-ms; origin scope; discovery and command timeoutsPage-declared WebMCP registrations as untrusted declarations; it never invokes them
rea capture-web-screenshot ENDPOINT TARGET_IDEndpoint and target IDOrigin scope; discovery and command timeoutsOne visible-viewport PNG artifact

The endpoint must be an explicit-port loopback CDP HTTP URL such as http://127.0.0.1:9222 or an accepted loopback browser WebSocket URL. A target ID is specific to the browser instance, so target discovery normally comes first. The browser socket form is supported by passive commands that can discover or inspect a page. Scenario attach mode still uses HTTP discovery.

analyze-web-bundle also supports Evidence delivery controls. Complete Evidence is the default. --detail summary requires --evidence_output and can use --view to request a JSON web-bundle or JavaScript-routes view while saving the complete Evidence bundle. These controls let a caller keep the CLI result small without discarding the source Evidence needed for later inspection.

References: src/…/browserCommands.ts• L46-334 src/…/browserAdvancedCommands.ts• L32-220 src/…/javascriptRouteDelivery.ts• L4-19 src/…/analysisEvidenceDelivery.ts• L25-35 src/cliObservationOptions.ts• L5-53 src/…/browserObservation.ts• L80-137 src/cliCommandNames.ts• L128-142

Browser comparison commands

Comparison commands work on saved Evidence and artifacts rather than on a live page. They accept each JSON value either inline or as a local file, which lets callers compare large scenario captures and PNG artifacts without exceeding command-line length limits.

CommandRequired argumentsMain optionsResult
rea compare-web-captures BEFORE_JSON AFTER_JSONEarlier and later passive capture or scenario JSON--normalization-json for scenario comparison rulesA structured comparison of web capture changes
rea compare-web-screenshots BEFORE_JSON AFTER_JSONEarlier and later screenshot artifact JSON--channel-threshold for per-channel pixel differencesA structured screenshot difference result

The capture comparison selects the passive or scenario contract from the supplied JSON shape. Scenario comparisons can apply a recorded literal normalization policy. Screenshot comparison uses self-verifying PNG artifacts and a channel threshold to control which pixel changes count.

References: src/…/browserAdvancedCommands.ts• L109-169 src/…/browserAdvancedCommands.ts• L223-272 src/…/browserAdvancedCommands.ts• L275-313

Browser scenario command

rea capture-browser-scenario INPUT_JSON runs one bounded browser scenario. INPUT_JSON can be inline JSON or a path to a JSON file. The command validates the complete scenario before it opens the browser, resolves a relative browser.executable_path from the input file when needed, and then returns the capture as Evidence.

The scenario request has these main parts:

  • browser: use mode: "launch" with an absolute browser executable path, or mode: "connect" with a loopback CDP endpoint and target ID. Launch mode defaults to headless execution and uses a temporary profile.
  • start_url: the initial HTTP(S) URL. Secret query values use declared references rather than inline secret text.
  • environment: optional viewport, locale, time zone, color scheme, reduced-motion, and service-worker settings. Defaults provide a stable 1280×720, en-US, UTC, light, reduced-motion context with service workers blocked.
  • actions: one or more steps. The fixed action set covers navigation, click, fill, key press, option selection, check or uncheck, locator-state waits, and timed waits. Each step has a unique step_id and may have an action timeout.
  • storage: optional cookies, local storage, and session storage seeds.
  • secrets: environment-variable names for values used by URLs, actions, storage, or redaction. Secret values are not placed in the JSON request.
  • capture: requested snapshots after each step or at the end, plus event families and optional network content. The default is only a final sanitized URL.
  • command_timeout_ms: an optional limit for browser commands such as connection, target discovery, and cleanup.

The scenario runtime opens the selected browser context, applies the declared state, visits the start URL, executes steps in order, and records the initial state plus one result per step. It retains only the artifacts and event families requested by the scenario. A connected scenario admits one active run for a target and restores the temporary environment changes before it disconnects. After a launch, the provider closes the owned browser and removes its temporary profile. After a connect, it leaves the external browser running.

References: src/cliBrowserScenarioCommands.ts• L20-100 src/…/browserScenario.ts• L16-137 src/…/browserScenarioValues.ts• L67-91 src/…/browserScenarioValues.ts• L159-225 src/…/browserScenarioValues.ts• L233-307 src/…/PlaywrightScenarioSession.ts• L138-269 src/…/PlaywrightScenarioSession.ts• L396-495 docs/browser-scenario-contract.md• L3-27

Electron browser workflows

Electron commands cover the same two broad modes for local desktop apps: passive inspection of pages exposed through an Electron CDP endpoint and an owned scenario that drives an Electron application. They use Electron-specific endpoints and input contracts, but they remain part of the CLI analysis boundary and return structured analysis results.

CommandRequired argumentsMain purpose
rea list-electron-targets ENDPOINTLiteral-loopback Electron CDP endpointFind local file-page targets
rea inspect-electron-page ENDPOINT TARGET_IDEndpoint and target IDObserve one Electron page during a bounded window
rea capture-electron-scenario INPUT_JSONInline scenario JSON or a JSON file pathRun a cancellable scenario with an owned Electron application

Static Electron commands such as inspect-electron-fuses and analyze-javascript-application do not attach to a live page. They support the wider application-analysis workflow, but they are separate from browser-context and browser-scenario capture.

References: src/…/electronCommands.ts• L27-38 src/…/electronCommands.ts• L84-145 src/…/electronCommands.ts• L180-263 src/…/electronCommands.ts• L266-317

Browser runtime relationship

The CLI is a thin command boundary over separate passive and controlled browser providers. Passive web commands create a fresh CDP provider and pass validated input to the browser observation service. Scenario capture creates a Playwright scenario provider only when the command runs, so browser automation support is not required during normal CLI startup. src/cli.ts registers both command families in the one-shot CLI.

This diagram shows how command input becomes provider work and then Evidence.

flowchart LR
    A[CLI command] --> B{Workflow}
    B -->|Passive context| C[Validate endpoint, target, and scope]
    C --> D[CDP observation provider]
    B -->|Scenario| E[Read and validate scenario JSON]
    E --> F[Playwright scenario provider]
    D --> G[Browser observation service]
    F --> H[Scenario capture service]
    G --> I[Evidence]
    H --> I
    I --> J[TOON or JSON CLI output]

Passive and scenario providers stay separate because their authority is different. CDP commands inspect an existing target and return limits or incomplete-coverage facts when the browser cannot provide all requested data. Scenario commands control a bounded flow and report action status, artifact state, event bounds, cleanup, and limitations. A connected scenario serializes access to the selected target, restores its temporary emulation state, and only then disconnects. Cancellation reaches both providers through the command boundary.

References: src/cli.ts• L163-175 src/cliBrowserContext.ts• L1-14 src/…/browserObservation.ts• L1-6 src/…/browserScenario.ts• L1-11 src/…/BrowserObservationService.ts• L24-112 src/…/BrowserScenarioCaptureService.ts• L10-37 src/…/PlaywrightScenarioSession.ts• L75-136 src/…/PlaywrightScenarioSession.ts• L475-560

Browser input and output boundaries

Input validation is part of the command contract. Passive endpoint values are limited to loopback CDP addresses, and origin filters contain only exact scheme, host, and port values. Scenario validation rejects unsupported fields, duplicate IDs, raw URL credentials, and undeclared secret references.

Every successful browser operation returns Evidence rather than an unstructured browser dump. The result records the operation input, provider identity, observed data, and completeness or limitation facts. A failed passive operation is projected as Browser observation failed. A failed scenario is projected as Browser scenario capture failed. Invalid JSON and schema errors remain structured input errors.

The CLI uses the normal output selection described by the parent command-line interface: use --json for machine-readable output. Browser bundle analysis can also use --detail summary with --evidence_output to return a small view while saving complete Evidence. --view selects the supported bundle or JavaScript-routes view and is valid only with that summary delivery. Comparison commands accept their JSON values either inline or from files, which avoids command-line length limits for embedded image data.

References: src/…/browserObservation.ts• L27-41 src/…/browserObservation.ts• L80-137 src/…/browserScenario.ts• L104-137 src/…/BrowserEvidence.ts• L41-80 src/cliBrowserContext.ts• L10-14 src/cliBrowserScenarioCommands.ts• L95-100 src/…/browserAdvancedCommands.ts• L251-275 src/…/javascriptRouteDelivery.ts• L4-19 src/…/analysisEvidenceDelivery.ts• L50-62

Browser workflow sequence

An attach-only investigation first discovers a target and then uses that target for one or more bounded observations. A controlled investigation instead defines its browser, state, actions, and requested evidence in one scenario input.

  1. Start or identify a Chromium-family browser with a loopback CDP port.
  2. Run list-browser-targets ENDPOINT --json and select the target that matches the page of interest.
  3. Run one or more page commands with the endpoint and target ID. Add an exact origin filter when the browser contains unrelated pages.
  4. Save the Evidence output when a later comparison or analysis view needs the result.
  5. For repeatable interaction, replace the separate attach calls with capture-browser-scenario SCENARIO_JSON --json.
  6. Compare saved captures with compare-web-captures or screenshots with compare-web-screenshots when the question is about change.

This sequence keeps discovery separate from inspection. It also prevents a passive command from being mistaken for an automation command: passive CDP observation does not navigate or drive the page.

References: src/…/browserCommands.ts• L57-105 src/…/browserCommands.ts• L107-165 src/cliBrowserScenarioCommands.ts• L26-92 docs/browser-observation.md• L169-202 docs/browser-scenario-contract.md• L30-56

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep CLI_COMMANDS, command registration, and the documented command table aligned when a browser command is added, renamed, or removed.
  • Keep CLI option names mapped to the snake-case domain fields consumed by the browser input schemas.
  • Keep browser discovery and command timeout options aligned with the provider operations that honor them.
  • Keep bundle-analysis delivery options aligned with the view schema and the rule that summary delivery must publish complete Evidence.
  • Preserve the distinction between loopback CDP attach authority and Playwright scenario ownership when changing provider composition or cleanup.
  • Preserve one-at-a-time admission and environment restoration for scenarios that connect to the same browser target.
  • Update scenario input guidance when action kinds, capture kinds, secret references, browser launch/connect rules, or command timeouts change.
  • Keep Electron endpoint rules and relative application-path resolution aligned with the Electron input contracts when Electron CLI commands change.
  • Keep Evidence error labels and completeness or limitation fields aligned with the provider errors exposed to CLI callers.

Important failure modes

TriggerConsequenceGuard
The endpoint is not an accepted loopback CDP HTTP or browser WebSocket URLTarget discovery and passive commands fail before observationUse an explicit loopback address and port; do not use localhost, LAN addresses, or unsupported URL paths
A target ID is stale or belongs to another browser instanceThe selected page cannot be attached or its current scope no longer matchesRun list-browser-targets again for the same endpoint
analyze-web-bundle requests summary delivery without --evidence_outputInput validation fails before bundle analysisProvide a non-overwriting Evidence output path when using --detail summary
--view does not match the supported bundle view or is used without summary deliveryBundle analysis input validation failsUse a valid view with --detail summary and --evidence_output
Two connected scenarios use the same endpoint and target at onceOne scenario waits for the active run instead of changing the target concurrentlyReuse the target only through the scenario admission flow and allow the first run to release it
A scenario references an undeclared secret or uses duplicate IDsScenario validation fails before browser work startsDeclare each secret and keep action and secret identifiers unique
A scenario asks only for the final URL after a page changes in placeThe capture cannot show the rendered resultRequest dom, accessibility, or another artifact that answers the question
A connected scenario cannot restore page state or a launched browser cannot closeThe result includes cleanup failure or incomplete resource stateTreat cleanup fields as part of the operation result and retry the retained cleanup lease when offered
A passive capture exceeds CDP message or collection limitsThe result is incomplete or fails with a structured browser errorNarrow origins and selected content, then read completeness and limitation fields
An Electron scenario points to an invalid application or executable pathThe owned app cannot start and the capture returns a structured Electron failureResolve paths from the scenario file when needed and use a valid local application

Key files

FileWhy to read it
src/cli.tsShows where browser command groups enter the one-shot CLI.
src/…/browserCommands.tsDefines passive target, page, bundle, and session commands.
src/…/browserAdvancedCommands.tsDefines WebMCP, screenshot, and capture-comparison commands.
src/…/javascriptRouteDelivery.tsDefines the bundle-analysis view and Evidence delivery options exposed by the CLI.
src/…/analysisEvidenceDelivery.tsDefines summary delivery, complete Evidence output, and Evidence bundle publication.
src/cliBrowserScenarioCommands.tsDefines scenario JSON input, validation, provider startup, and cleanup.
src/…/electronCommands.tsDefines Electron target, page, scenario, and static application commands.
src/…/browserObservation.tsDefines CDP endpoint, origin, and passive inspection input boundaries.
src/…/browserScenario.tsDefines the top-level scenario contract and cross-field validation.
src/…/browserScenarioValues.tsDefines browser mode, actions, storage, secrets, and capture selections.
src/…/BrowserObservationService.tsConnects passive requests to Evidence-producing browser operations.
src/…/BrowserScenarioCaptureService.tsConnects controlled scenarios to scenario Evidence.
src/…/CdpBrowserProvider.tsIllustrates the attach-only browser authority behind context commands.
src/…/PlaywrightScenarioSession.tsIllustrates launch/connect ownership, target admission, state restoration, and the scenario lifecycle.