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.
| Family | Main purpose | Browser authority |
|---|---|---|
| Browser context | Find targets, inspect a page, inspect its bundle, watch user navigation, discover page-declared WebMCP tools, or capture a screenshot | Attaches to a loopback CDP browser and does not launch, navigate, evaluate, or close it |
| Browser scenario | Run a bounded sequence of actions and retain selected page state and events | Launches 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 comparison | Compare saved passive captures, scenario captures, or screenshot artifacts | Reads 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.
| Command | Required arguments | Main options | Result |
|---|---|---|---|
rea list-browser-targets ENDPOINT | Loopback CDP HTTP endpoint or browser WebSocket URL | --allowed-origins; discovery timeout | Eligible page targets and their current URLs and titles |
rea inspect-web-page ENDPOINT TARGET_ID | Endpoint 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 fingerprints | Bounded page, resource, event, and selected content observations |
rea analyze-web-bundle ENDPOINT TARGET_ID | Endpoint and target ID | --observation-ms; semantic-precision JSON; source-map fetching and limits; heap and analysis-time controls; Evidence delivery controls | Static script and bundle findings such as chunks, routes, endpoints, and source-map evidence |
rea observe-web-session ENDPOINT TARGET_ID | Endpoint and target ID | --observation-ms; origin scope; discovery and command timeouts | Ordered navigation and target-lifecycle events during a user-driven window |
rea discover-webmcp-tools ENDPOINT TARGET_ID | Endpoint and target ID | --observation-ms; origin scope; discovery and command timeouts | Page-declared WebMCP registrations as untrusted declarations; it never invokes them |
rea capture-web-screenshot ENDPOINT TARGET_ID | Endpoint and target ID | Origin scope; discovery and command timeouts | One 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.
| Command | Required arguments | Main options | Result |
|---|---|---|---|
rea compare-web-captures BEFORE_JSON AFTER_JSON | Earlier and later passive capture or scenario JSON | --normalization-json for scenario comparison rules | A structured comparison of web capture changes |
rea compare-web-screenshots BEFORE_JSON AFTER_JSON | Earlier and later screenshot artifact JSON | --channel-threshold for per-channel pixel differences | A 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: usemode: "launch"with an absolute browser executable path, ormode: "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 uniquestep_idand 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.
| Command | Required arguments | Main purpose |
|---|---|---|
rea list-electron-targets ENDPOINT | Literal-loopback Electron CDP endpoint | Find local file-page targets |
rea inspect-electron-page ENDPOINT TARGET_ID | Endpoint and target ID | Observe one Electron page during a bounded window |
rea capture-electron-scenario INPUT_JSON | Inline scenario JSON or a JSON file path | Run 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.
- Start or identify a Chromium-family browser with a loopback CDP port.
- Run
list-browser-targets ENDPOINT --jsonand select the target that matches the page of interest. - Run one or more page commands with the endpoint and target ID. Add an exact origin filter when the browser contains unrelated pages.
- Save the Evidence output when a later comparison or analysis view needs the result.
- For repeatable interaction, replace the separate attach calls with
capture-browser-scenario SCENARIO_JSON --json. - Compare saved captures with
compare-web-capturesor screenshots withcompare-web-screenshotswhen 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
| Trigger | Consequence | Guard |
|---|---|---|
| The endpoint is not an accepted loopback CDP HTTP or browser WebSocket URL | Target discovery and passive commands fail before observation | Use 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 instance | The selected page cannot be attached or its current scope no longer matches | Run list-browser-targets again for the same endpoint |
analyze-web-bundle requests summary delivery without --evidence_output | Input validation fails before bundle analysis | Provide a non-overwriting Evidence output path when using --detail summary |
--view does not match the supported bundle view or is used without summary delivery | Bundle analysis input validation fails | Use a valid view with --detail summary and --evidence_output |
| Two connected scenarios use the same endpoint and target at once | One scenario waits for the active run instead of changing the target concurrently | Reuse 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 IDs | Scenario validation fails before browser work starts | Declare each secret and keep action and secret identifiers unique |
| A scenario asks only for the final URL after a page changes in place | The capture cannot show the rendered result | Request dom, accessibility, or another artifact that answers the question |
| A connected scenario cannot restore page state or a launched browser cannot close | The result includes cleanup failure or incomplete resource state | Treat cleanup fields as part of the operation result and retry the retained cleanup lease when offered |
| A passive capture exceeds CDP message or collection limits | The result is incomplete or fails with a structured browser error | Narrow origins and selected content, then read completeness and limitation fields |
| An Electron scenario points to an invalid application or executable path | The owned app cannot start and the capture returns a structured Electron failure | Resolve paths from the scenario file when needed and use a valid local application |
Key files
| File | Why to read it |
|---|---|
| src/cli.ts | Shows where browser command groups enter the one-shot CLI. |
| src/…/browserCommands.ts | Defines passive target, page, bundle, and session commands. |
| src/…/browserAdvancedCommands.ts | Defines WebMCP, screenshot, and capture-comparison commands. |
| src/…/javascriptRouteDelivery.ts | Defines the bundle-analysis view and Evidence delivery options exposed by the CLI. |
| src/…/analysisEvidenceDelivery.ts | Defines summary delivery, complete Evidence output, and Evidence bundle publication. |
| src/cliBrowserScenarioCommands.ts | Defines scenario JSON input, validation, provider startup, and cleanup. |
| src/…/electronCommands.ts | Defines Electron target, page, scenario, and static application commands. |
| src/…/browserObservation.ts | Defines CDP endpoint, origin, and passive inspection input boundaries. |
| src/…/browserScenario.ts | Defines the top-level scenario contract and cross-field validation. |
| src/…/browserScenarioValues.ts | Defines browser mode, actions, storage, secrets, and capture selections. |
| src/…/BrowserObservationService.ts | Connects passive requests to Evidence-producing browser operations. |
| src/…/BrowserScenarioCaptureService.ts | Connects controlled scenarios to scenario Evidence. |
| src/…/CdpBrowserProvider.ts | Illustrates the attach-only browser authority behind context commands. |
| src/…/PlaywrightScenarioSession.ts | Illustrates launch/connect ownership, target admission, state restoration, and the scenario lifecycle. |