Actions

Every browser action goes through POST /command on the daemon at http://127.0.0.1:17373. Requests carry the Bearer token printed by omw connection. The CLI wraps it in omw call, the SDK in call (see CLI and SDK).

RequestsCopy Anchor Link

The body is one JSON object of at most 2 MiB with no unknown fields. A session name that repeats a binding is routed by the rules on Sessions and tabs.

{
  "session": "research",
  "action": "navigate",
  "args": { "url": "https://example.com", "group_title": "Research" },
  "timeoutMs": 30000
}

The body can also carry id, a string that the reply repeats. Without it, the daemon assigns a Snowflake ID in lowercase base 36. A successful call returns the id and the action result:

{
  "id": "uvwoyqsusjk",
  "result": { "success": true, "tabId": 412, "url": "https://example.com/" }
}

A failed call returns the id and a fault instead of a result, with an HTTP status from the Errors table:

{
  "id": "uvwoyqsusjk",
  "error": { "code": "stale_ref", "message": "element reference expired; take a fresh snapshot" }
}

Page actions run in the session's current tab. Pass tabId (or tab) to address another tab the session holds without switching to it.

Navigation and tabsCopy Anchor Link

A session holds at most 32 tabs across task and borrowed ones.

ReadingCopy Anchor Link

InputCopy Anchor Link

WaitingCopy Anchor Link

wait returns as soon as the condition holds, and checks it again every 75 ms. When the condition has not held 500 ms before the request deadline, wait fails with wait_timeout. It checks at least once, also under a deadline of 500 ms or less. Set the deadline with timeoutMs, or --timeout-ms in omw call. Set one of these fields:

FramesCopy Anchor Link

While a frame is selected, page actions run in it. Selecting a frame drops the previous references and requires a new snapshot.

A selection ends when its frame navigates or is removed, or, in Chrome, when the tab's debugger session ends, for example after the user cancels Chrome's debugging bar or the extension's worker restarts. The next action that would run in the frame fails once with frame_unavailable; later actions use the main frame.

Files and captureCopy Anchor Link

A screenshot whose encoded result exceeds 32 MiB fails with result_too_large.

Network, console, storage and cookiesCopy Anchor Link

EmulationCopy Anchor Link

Settings persist for the session and apply to new tabs before they navigate. Chrome drops them when it ends a tab's debugger session, for example after the extension's worker restarts; the next command on a task tab of the session applies them again. Borrowed tabs are excluded.

BatchCopy Anchor Link

batch takes steps, an array of { action, args } objects, 1 to 64 entries. Steps run in order in one request and stop at the first error. The error keeps the code of the failed step, and its message starts with batch step N of M (action):, so steps 1 to N-1 completed. Completed steps are not rolled back. batch, close_session, screenshot, save_as_pdf, artifact_read and artifact_close cannot appear inside a batch.

PresetsCopy Anchor Link

The configuration is stored on the session and applied to task tabs. Borrowed tabs are excluded. navigate accepts the same fields and stores them once the navigation starts. See Page presets.

CDPCopy Anchor Link

cdp sends one Chrome DevTools Protocol command to the tab: method, params, and an optional sessionId for a child target. It returns the protocol result unchanged.

Two methods change the bridge's own state. Runtime.disable ends the frame selection of its session, and Page.disable without a session id invalidates the tab's @e references; the next snapshot or navigation re-enables the events.

The daemon uses cdp_attach, cdp_detach, artifact_read, artifact_close and list_targets internally. Do not send them yourself.

SelectorsCopy Anchor Link

Every action that takes selector accepts these forms.

Append >>nth=0 to take the first match or >>nth=-1 to take the last. Text, CSS and attribute locators traverse open shadow roots. Closed shadow roots stay invisible to them.

Reference lifetimeCopy Anchor Link

@e references belong to one document generation. Each snapshot numbers its references under a new generation, a Snowflake ID in base 36. In Chrome, a new snapshot, a frame selection, a new main document (navigation or reload) or a change of the tab's URL invalidates them. A snapshot taken inside a selected frame also expires when that frame navigates, reloads, is removed, or the selection ends. Other iframes loading or navigating leave it valid. In Firefox, references live in the document that produced them; see Firefox.

ErrorsCopy Anchor Link

Every fault carries code and message. The HTTP status is shown below; a code not listed here returns 502.