---
title: Python API Reference
description: Every method in the Vibium Python client with its typed signature, and the matching CLI command and MCP tool.
tableOfContents:
  maxHeadingLevel: 2
---

<!-- Generated by scripts/gen_api_reference.py from docs/reference/api.md and the nightly packages in VibiumDev/vibium. Do not edit. -->

All 186 entries of the Python client API, grouped by object. Each
entry shows the signature from the client's own source, then the
matching CLI command and MCP tool where one exists.

Entries marked **(nightly)** are not in the latest release (26.11.16);
**(changed in nightly)** means the documented signature differs from that release.
Signatures come from the latest nightly build. See
[What's in Nightly](../../nightly.md). The same data for every surface
is in the [API matrix](../../reference/api-matrix.md) and in
[`/api.json`](/api.json).

Examples assume `bro` is a started browser and `vibe` is its page, as in the
[quickstart](index.md).

Signatures are for the sync API (`from vibium import browser`). The async
API in `vibium.async_api` has the same methods as coroutines.

## Browser

**`browser.start(opts?)`**

Launch browser and connect

```text
start(
    url: Optional[str] = None,
    *,
    engine: Optional[str] = None,
    channel: Optional[str] = None,
    headless: bool = False,
    user_data_dir: Optional[str] = None,
    headers: Optional[dict] = None,
    caps: Optional[dict] = None,
    executable_path: Optional[str] = None,
) -> Browser
```

Start a browser session.

Example: `bro = browser.start(headless=True)`

CLI `vibium start` · MCP `browser_start`

**`browser.page()`**

Get the default page

`page() -> Page`

Get the default page (first browsing context).

Example: `vibe = bro.page()`

**`browser.new_page()`**

Create a new page

`new_page() -> Page`

Create a new page (tab) in the default context.

Example: `second = bro.new_page()`

CLI `vibium page new` · MCP `browser_new_page`

**`browser.new_context()`**

Create a new browser context

`new_context() -> BrowserContext`

Create a new browser context (isolated, incognito-like).

**`browser.pages()`**

List all pages

`pages() -> List[Page]`

Get all open pages.

CLI `vibium pages` · MCP `browser_list_pages`

**`browser.stop()`**

Stop the browser

`stop() -> None`

Stop the browser and clean up.

Example: `bro.stop()`

CLI `vibium stop` · MCP `browser_stop`

**`browser.on_page(cb)`**

Listen for new page events

`on_page(callback: Callable[[Page], None]) -> None`

Register a callback for when a new page is created.

**`browser.on_popup(cb)`**

Listen for popup events

`on_popup(callback: Callable[[Page], None]) -> None`

Register a callback for when a popup is opened.

**`browser.remove_all_listeners(ev?)`**

Remove all event listeners

`remove_all_listeners(event: Optional[str] = None) -> None`

Remove all listeners for 'page', 'popup', or all.

## Page

**`page.go(url)`**

Navigate to a URL

`go(url: str) -> None`

Example: `vibe.go("https://example.com")`

CLI `vibium go <url>` · MCP `browser_navigate`

**`page.back()`**

Go back

`back() -> None`

Navigate back in history.

Example: `vibe.back()`

CLI `vibium back` · MCP `browser_back`

**`page.forward()`**

Go forward

`forward() -> None`

Navigate forward in history.

CLI `vibium forward` · MCP `browser_forward`

**`page.reload()`**

Reload page

`reload() -> None`

Reload the page.

Example: `vibe.reload()`

CLI `vibium reload` · MCP `browser_reload`

**`page.url()`**

Get current URL

`url() -> str`

Get the current page URL.

Example: `url = vibe.url()`

CLI `vibium url` · MCP `browser_get_url`

**`page.title()`**

Get page title

`title() -> str`

Get the current page title.

Example: `title = vibe.title()`

CLI `vibium title` · MCP `browser_get_title`

**`page.content()`**

Get page HTML

`content() -> str`

Get the full HTML content of the page.

Example: `html = vibe.content()`

**`page.find(locator, **opts)`**

Find a single element by description (a bare string), css, tag, semantic locator, or reference image; strategy auto, cv, vlm, or tree

```text
find(
    selector: Optional[str] = None,
    /,
    *,
    description: Optional[str] = None,
    image: Optional[ImageInput] = None,
    css: Optional[str] = None,
    tag: Optional[str] = None,
    name: Optional[str] = None,
    role: Optional[str] = None,
    text: Optional[str] = None,
    label: Optional[str] = None,
    placeholder: Optional[str] = None,
    alt: Optional[str] = None,
    title: Optional[str] = None,
    testid: Optional[str] = None,
    xpath: Optional[str] = None,
    near: Optional[str] = None,
    strategy: Optional[str] = None,
    details: Optional[bool] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
    timeout: Optional[int] = None,
) -> Element
```

Find an element; see the async page.find for the forms.

Example: `button = vibe.find(role="button", text="Submit")`

CLI `vibium find <description>` · MCP `browser_find`

**`page.find_all(locator, **opts)`**

Find all matching elements, same locator forms

```text
find_all(
    selector: Optional[str] = None,
    /,
    *,
    description: Optional[str] = None,
    image: Optional[ImageInput] = None,
    css: Optional[str] = None,
    tag: Optional[str] = None,
    name: Optional[str] = None,
    role: Optional[str] = None,
    text: Optional[str] = None,
    label: Optional[str] = None,
    placeholder: Optional[str] = None,
    alt: Optional[str] = None,
    title: Optional[str] = None,
    testid: Optional[str] = None,
    xpath: Optional[str] = None,
    near: Optional[str] = None,
    strategy: Optional[str] = None,
    details: Optional[bool] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
    timeout: Optional[int] = None,
) -> List[Element]
```

Find all matching elements; see the async page.find_all.

Example: `links = vibe.find_all(role="link")`

CLI `vibium find --all <description>` · MCP `browser_find_all`

**`page.screenshot(opts?)`**

Take a page screenshot

`screenshot(full_page: Optional[bool] = None, clip: Optional[Dict[str, Any]] = None) -> bytes`

Take a screenshot. Returns PNG bytes.

Example: `Path("page.png").write_bytes(vibe.screenshot())`

CLI `vibium screenshot` · MCP `browser_screenshot`

**`page.pdf(**opts)`**

Generate PDF

`pdf(**options: Any) -> bytes`

Print the page to PDF. Same keyword options as the async API: landscape, scale, background, margin_top/bottom/left/right, page_width, page_height, page_ranges, shrink_to_fit.

CLI `vibium pdf` · MCP `browser_pdf`

**`page.evaluate(expr)`**

Evaluate JavaScript

`evaluate(expression: str) -> Any`

Evaluate a JS expression and return the deserialized value.

Example: `count = vibe.evaluate("document.links.length")`

CLI `vibium eval <expr>` · MCP `browser_evaluate`

**`page.add_script(src)`**

Add a script tag

`add_script(source: str) -> None`

Inject a script into the page. Pass a URL or inline JavaScript.

**`page.add_style(src)`**

Add a style tag

`add_style(source: str) -> None`

Inject a stylesheet into the page. Pass a URL or inline CSS.

**`page.expose(name, fn)`**

Expose a function to the page

`expose(name: str, fn: Union[str, Callable[..., Any]]) -> None`

Expose a function on window.

**`page.wait(ms)`**

Wait for a duration

`wait(ms: int) -> None`

Wait for a fixed amount of time (milliseconds).

CLI `vibium sleep <ms>` · MCP `browser_sleep`

**`page.wait_for_function(fn, **opts)`**

Wait for JS function to return truthy

`wait_for_function(fn: str, timeout: Optional[int] = None) -> Any`

Wait until a function returns a truthy value.

Example: `vibe.wait_for_function('document.readyState === "complete"')`

CLI `vibium wait fn <expr>` · MCP `browser_wait_for_fn`

**`page.wait_for_url(url, **opts)`**

Wait for URL to match

`wait_for_url(pattern: str, timeout: Optional[int] = None) -> None`

Wait until the page URL matches a pattern.

Example: `vibe.wait_for_url("**/next")`

CLI `vibium wait url <pat>` · MCP `browser_wait_for_url`

**`page.wait_for_load(**opts)`**

Wait for page load

`wait_for_load(state: Optional[str] = None, timeout: Optional[int] = None) -> None`

Wait until the page reaches a load state.

Example: `vibe.wait_for_load()`

CLI `vibium wait load` · MCP `browser_wait_for_load`

**`page.scroll(dir?, amt?, sel?)`**

Scroll the page

`scroll(direction: str = 'down', amount: int = 3, selector: Optional[str] = None) -> None`

Scroll the page in a direction (up/down/left/right).

CLI `vibium scroll <dir> <amt>` · MCP `browser_scroll`

**`page.set_viewport(size)`**

Set viewport size

`set_viewport(size: Dict[str, int]) -> None`

Set the viewport size. size: {width, height}.

Example: `vibe.set_viewport({"width": 375, "height": 812})`

CLI `vibium viewport <w> <h>` · MCP `browser_set_viewport`

**`page.viewport()`**

Get viewport size

`viewport() -> Dict[str, int]`

Get the current viewport size.

CLI `vibium viewport` · MCP `browser_get_viewport`

**`page.emulate_media(**opts)`**

Override CSS media features

```text
emulate_media(
    *,
    media: Optional[str] = None,
    color_scheme: Optional[str] = None,
    reduced_motion: Optional[str] = None,
    forced_colors: Optional[str] = None,
    contrast: Optional[str] = None,
) -> None
```

CLI `vibium media <scheme>` · MCP `browser_emulate_media`

**`page.set_content(html)`**

Set page HTML

`set_content(html: str) -> None`

Replace the page HTML content.

Example: `vibe.set_content("<h1>Hello</h1>")`

CLI `vibium content <html>` · MCP `browser_set_content`

**`page.set_geolocation(coords)`**

Override geolocation

`set_geolocation(coords: Dict[str, float]) -> None`

Override the browser's geolocation.

CLI `vibium geolocation <lat> <lon>` · MCP `browser_set_geolocation`

**`page.set_window(**opts)`**

Set window size/position

`set_window(**options: Any) -> None`

Set the OS browser window size, position, or state.

CLI `vibium window <opts>` · MCP `browser_set_window`

**`page.window()`**

Get window info

`window() -> Dict[str, Any]`

Get the current OS browser window state and dimensions.

CLI `vibium window` · MCP `browser_get_window`

**`page.a11y_tree(opts?)`**

Get accessibility tree

`a11y_tree(everything: Optional[bool] = None, root: Optional[str] = None) -> A11yNode`

Get the accessibility tree for the page.

Example: `tree = vibe.a11y_tree()`

CLI `vibium a11y-tree` · MCP `browser_a11y_tree`

**`page.frames()`**

List all frames

`frames() -> List[Page]`

Get all child frames of this page.

CLI `vibium frames` · MCP `browser_frames`

**`page.frame(name_or_url)`**

Get a frame by name/URL

`frame(name_or_url: str) -> Optional[Page]`

Find a frame by name or URL substring.

CLI `vibium frame <ref>` · MCP `browser_frame`

**`page.main_frame()`**

Get the main frame

`main_frame() -> Page`

Returns this page — the page IS its own main frame.

**`page.bring_to_front()`**

Bring page to front

`bring_to_front() -> None`

Bring this page to the foreground.

CLI `vibium page switch <idx>` · MCP `browser_switch_page`

**`page.close()`**

Close the page

`close() -> None`

Close this page.

CLI `vibium page close` · MCP `browser_close_page`

**`page.route(pattern, handler)`**

Register a route handler

`route(pattern: str, action: Union[str, Dict[str, Any], Callable[[Route], None]]) -> None`

Intercept network requests.

**`page.unroute(pattern)`**

Remove a route handler

`unroute(pattern: str) -> None`

Remove a previously registered route.

**`page.set_headers(headers)`**

Set extra HTTP headers

`set_headers(headers: Dict[str, str]) -> None`

Set extra HTTP headers for all requests in this page.

**`page.on_request(fn)`**

Listen for requests

`on_request(fn: Callable) -> None`

Register a callback for every outgoing request.

Example: `vibe.on_request(lambda req: print(req.method(), req.url()))`

**`page.on_response(fn)`**

Listen for responses

`on_response(fn: Callable) -> None`

Register a callback for every completed response.

Example: `vibe.on_response(lambda resp: print(resp.status(), resp.url()))`

**`page.on_dialog(fn)`**

Listen for dialogs

`on_dialog(action: Union[str, Callable]) -> None`

Handle browser dialogs.

**`page.on_console(fn)`**

Listen for console messages

`on_console(mode: str = 'collect') -> None`

Start collecting console messages. Retrieve with console_messages().

Example: `vibe.on_console(lambda msg: print(msg.type(), msg.text()))`

**`page.on_error(fn)`**

Listen for page errors

`on_error(mode: str = 'collect') -> None`

Start collecting page errors. Retrieve with errors().

**`page.on_download(fn)`**

Listen for downloads

`on_download(fn: Callable) -> None`

Register a callback for file downloads.

**`page.on_web_socket(fn)`**

Subscribe to WebSocket events

`on_web_socket(fn: Callable) -> None`

Listen for WebSocket connections opened by the page.

**`page.remove_all_listeners(ev?)`**

Remove all event listeners

`remove_all_listeners(event: Optional[str] = None) -> None`

Remove all listeners for a given event, or all events.

**`page.capture.response(pat, fn?)`**

Capture response (before action)

```text
response(
    pattern: str,
    fn: Optional[Callable] = None,
    timeout: Optional[int] = None,
) -> Union[Dict[str, Any], _SyncCapturedResponse]
```

Wait for a response matching a URL pattern.

Example: `resp = vibe.capture.response("**/api/users", lambda: vibe.find(role="button", text="Users").click())`

**`page.capture.request(pat, fn?)`**

Capture request (before action)

```text
request(
    pattern: str,
    fn: Optional[Callable] = None,
    timeout: Optional[int] = None,
) -> Union[Dict[str, Any], _SyncCapturedRequest]
```

Wait for a request matching a URL pattern.

**`page.capture.navigation(fn?)`**

Capture navigation (before action)

`navigation(fn: Optional[Callable] = None, timeout: Optional[int] = None) -> Union[str, _SyncCapturedNavigation]`

Wait for a navigation event. Resolves with URL string.

**`page.capture.event(name, fn?)`**

Capture event (before action)

`event(name: str, fn: Optional[Callable] = None, timeout: Optional[int] = None) -> Union[Any, _SyncCapturedEvent]`

Wait for a named event.

**`page.capture.download(fn?)`**

Capture download (before action)

`download(fn: Optional[Callable] = None, timeout: Optional[int] = None) -> Union[SyncDownload, _SyncCapturedDownload]`

Wait for a download event.

Example: `download = vibe.capture.download(lambda: vibe.find(role="link", text="Download").click())`

**`page.capture.dialog(fn?)`**

Capture dialog (before action)

`dialog(fn: Optional[Callable] = None, timeout: Optional[int] = None) -> Union[Dict[str, Any], _SyncCapturedDialog]`

Wait for a dialog event. The dialog is dismissed as soon as it is captured, so a fn that blocks on it (e.g. a synchronous alert() via evaluate) gets unblocked instead of deadlocking.

**`page.console_messages()`**

Get buffered console messages

`console_messages() -> List[Dict[str, str]]`

Return collected console messages.

**`page.errors()`**

Get buffered page errors

`errors() -> List[Dict[str, str]]`

Return collected errors.

**`page.context`**

Owning browser context

`context: BrowserContextType  # property`

The parent BrowserContext that owns this page.

**`page.id`**

Browsing context id

`id: str  # property`

The browsing context ID for this page.

**`page.capture`**

One-shot capture namespace

`capture: _SyncCaptureNamespace  # property`

Capture namespace — set up a listener before performing an action.

**`page.keyboard`**

Keyboard input for the page

`keyboard: Keyboard  # property`

Page-level keyboard input.

**`page.mouse`**

Mouse input for the page

`mouse: Mouse  # property`

Page-level mouse input.

**`page.touch`**

Touch input for the page

`touch: Touch  # property`

Page-level touch input.

**`page.clock`**

Clock control for the page

`clock: Clock  # property`

Page-level clock control for faking timers and Date.

**`page.wait_until`**

Deprecated alias for the wait helpers

`wait_until: _SyncWaitUntilNamespace  # property`

Deprecated alias — use wait_for_function / wait_for_url / wait_for_load.

***mode of on_console('collect')***

Enable console collect mode

***mode of on_error('collect')***

Enable error collect mode

**`page.eval(expr)`**

Alias for evaluate

`eval(expression: str) -> Any`

Alias for :meth:`evaluate` (issue #144).

## Element

**`el.click(timeout?)`**

Click an element

`click(timeout: Optional[int] = None) -> None`

Click the element. Waits for the element to be visible, stable, receive events, and enabled.

Example: `vibe.find(role="button", text="Submit").click()`

CLI `vibium click <sel>` · MCP `browser_click`

**`el.dblclick(timeout?)`**

Double-click an element

`dblclick(timeout: Optional[int] = None) -> None`

Double-click the element.

CLI `vibium dblclick <sel>` · MCP `browser_dblclick`

**`el.fill(value, timeout?)`**

Fill an input field

`fill(value: str, timeout: Optional[int] = None) -> None`

Fill the element with text (clears existing content first). For inputs and textareas.

Example: `vibe.find(label="Email").fill("user@example.com")`

CLI `vibium fill <sel> <val>` · MCP `browser_fill`

**`el.type(text, timeout?)`**

Type text character by character

`type(text: str, timeout: Optional[int] = None) -> None`

Type text into the element (appends to existing content). Waits for the element to be visible, stable, receive events, enabled, and editable.

Example: `vibe.find(label="Email").type("user@example.com")`

CLI `vibium type <text>` · MCP `browser_type`

**`el.press(key, timeout?)`**

Press a key on focused element

`press(key: str, timeout: Optional[int] = None) -> None`

Press a key while the element is focused. Supports key names ("Enter", "Tab") and combos ("Control+a").

Example: `vibe.find(label="Email").press("Enter")`

CLI `vibium press <key>` · MCP `browser_press`

**`el.clear(timeout?)`**

Clear an input field

`clear(timeout: Optional[int] = None) -> None`

Clear the element's content (select all + delete).

**`el.set(value=True, timeout=...)`**

Check a checkbox

`set(value: bool = True, timeout: Optional[int] = None) -> None`

Check a checkbox (no-op if already checked).

Example: `vibe.find(css='input[type="checkbox"]').set()`

CLI `vibium set <sel>` · MCP `browser_set`

**`el.unset(timeout?)`**

Uncheck a checkbox

`unset(timeout: Optional[int] = None) -> None`

Uncheck a checkbox (no-op if already unchecked).

CLI `vibium unset <sel>` · MCP `browser_unset`

**`el.select_option(val, timeout?)`**

Select a dropdown option

`select_option(value: str, timeout: Optional[int] = None) -> None`

Select an option in a \<select\> element by value.

Example: `vibe.find(label="Country").select_option("de")`

CLI `vibium select <sel> <val>` · MCP `browser_select`

**`el.hover(timeout?)`**

Hover over an element

`hover(timeout: Optional[int] = None) -> None`

Hover over the element (move mouse to center, no click).

Example: `vibe.find(role="button", text="Menu").hover()`

CLI `vibium hover <sel>` · MCP `browser_hover`

**`el.focus(timeout?)`**

Focus an element

`focus(timeout: Optional[int] = None) -> None`

Focus the element.

CLI `vibium focus <sel>` · MCP `browser_focus`

**`el.drag_to(target, timeout?)`**

Drag an element to a target

`drag_to(target: Element, timeout: Optional[int] = None) -> None`

Drag this element to a target element.

CLI `vibium drag <sel> <x> <y>` · MCP `browser_drag`

**`el.tap(timeout?)`**

Tap an element (touch)

`tap(timeout: Optional[int] = None) -> None`

Tap the element (touch action).

**`el.scroll_into_view(timeout?)`**

Scroll element into view

`scroll_into_view(timeout: Optional[int] = None) -> None`

Scroll the element into view.

CLI `vibium scroll into-view <sel>` · MCP `browser_scroll_into_view`

**`el.dispatch_event(type, init?)`**

Dispatch a DOM event

`dispatch_event(event_type: str, event_init: Optional[Dict[str, Any]] = None, timeout: Optional[int] = None) -> None`

Dispatch a DOM event on the element.

**`el.set_files(files, timeout?)`**

Set files on a file input

`set_files(files: List[str], timeout: Optional[int] = None) -> None`

Set files on an \<input type="file"\> element.

CLI `vibium upload <sel> <paths>` · MCP `browser_upload`

**`el.highlight()`**

Highlight an element

`highlight(timeout: Optional[int] = None) -> None`

Briefly outline the element so a human watching can see it.

CLI `vibium highlight <sel>` · MCP `browser_highlight`

**`el.text()`**

Get element text content

`text() -> str`

Get the element's textContent (trimmed).

Example: `heading = vibe.find(css="h1").text()`

CLI `vibium text <sel>` · MCP `browser_get_text`

**`el.inner_text()`**

Get element inner text

`inner_text() -> str`

Get the element's innerText (rendered text only).

CLI `vibium text <sel>` · MCP `browser_get_text`

**`el.html()`**

Get element outer HTML

`html() -> str`

Get the element's innerHTML.

CLI `vibium html <sel>` · MCP `browser_get_html`

**`el.value()`**

Get input element value

`value() -> str`

Get the element's value (for inputs, textareas, selects).

Example: `email = vibe.find(label="Email").value()`

CLI `vibium value <sel>` · MCP `browser_get_value`

**`el.attr(name)`**

Get element attribute

`attr(name: str) -> Optional[str]`

Get an attribute value. Short name for get_attribute().

Example: `href = vibe.find(role="link", text="Next").attr("href")`

CLI `vibium attr <sel> <name>` · MCP `browser_get_attribute`

**`el.bounds()`**

Get element bounding box

`bounds() -> BoundingBox`

Get the element's bounding box. Short name for bounding_box().

**`el.bounding_box()`**

Bounding box (Playwright-compat alias for bounds)

`bounding_box() -> BoundingBox`

**`el.get_attribute(name)`**

Get attribute (alias for attr)

`get_attribute(name: str) -> Optional[str]`

**`el.info`**

Find-time snapshot of tag, text, and box

`info  # property`

Snapshot of tag, text, and box captured when the element was found.

**`el.is_visible()`**

Check if element is visible

`is_visible() -> bool`

Check if the element is visible (has dimensions, not display:none/visibility:hidden/opacity:0).

Example: `visible = vibe.find(role="button", text="Submit").is_visible()`

CLI `vibium is visible <sel>` · MCP `browser_is_visible`

**`el.is_hidden()`**

Check if element is hidden

`is_hidden() -> bool`

Check if the element is hidden (inverse of is_visible()).

**`el.is_enabled()`**

Check if element is enabled

`is_enabled() -> bool`

Check if the element is enabled (not disabled).

CLI `vibium is enabled <sel>` · MCP `browser_is_enabled`

**`el.is_set()`**

Check if element is checked

`is_set() -> bool`

Check if the element is checked (for checkboxes/radios).

CLI `vibium is set <sel>` · MCP `browser_is_set`

**`el.is_editable()`**

Check if element is editable

`is_editable() -> bool`

Check if the element is editable (not disabled and not readonly).

**`el.role()`**

Get element ARIA role

`role() -> str`

Get the element's computed ARIA role.

**`el.label()`**

Get element accessible label

`label() -> str`

Get the element's accessible name (label).

**`el.screenshot()`**

Screenshot an element

`screenshot() -> bytes`

Take a screenshot of just this element. Returns PNG bytes.

**`el.wait_until(state?, timeout?)`**

Wait for element state

`wait_until(state: Optional[str] = None, timeout: Optional[int] = None) -> None`

Wait until the element reaches a state: visible, hidden, attached, or detached.

CLI `vibium wait <sel> --state <st>` · MCP `browser_wait`

**`el.find(sel, **opts)`**

Find a child element (scoped)

```text
find(
    selector: Optional[str] = None,
    /,
    *,
    description: Optional[str] = None,
    image: Optional[ImageInput] = None,
    css: Optional[str] = None,
    tag: Optional[str] = None,
    name: Optional[str] = None,
    role: Optional[str] = None,
    text: Optional[str] = None,
    label: Optional[str] = None,
    placeholder: Optional[str] = None,
    alt: Optional[str] = None,
    title: Optional[str] = None,
    testid: Optional[str] = None,
    xpath: Optional[str] = None,
    near: Optional[str] = None,
    strategy: Optional[str] = None,
    details: Optional[bool] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
    timeout: Optional[int] = None,
) -> Element
```

Find a child element, scoped to this element; see the async page.find for the forms.

Example: `home = vibe.find(css="nav").find(role="link", text="Home")`

**`el.find_all(sel, **opts)`**

Find all child elements (scoped)

```text
find_all(
    selector: Optional[str] = None,
    /,
    *,
    description: Optional[str] = None,
    image: Optional[ImageInput] = None,
    css: Optional[str] = None,
    tag: Optional[str] = None,
    name: Optional[str] = None,
    role: Optional[str] = None,
    text: Optional[str] = None,
    label: Optional[str] = None,
    placeholder: Optional[str] = None,
    alt: Optional[str] = None,
    title: Optional[str] = None,
    testid: Optional[str] = None,
    xpath: Optional[str] = None,
    near: Optional[str] = None,
    strategy: Optional[str] = None,
    details: Optional[bool] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
    timeout: Optional[int] = None,
) -> List[Element]
```

Find all child elements, scoped to this element.

## BrowserContext

**`context.new_page()`**

Create a page in a context

`new_page() -> Page`

Create a new page (tab) in this context.

**`context.close()`**

Close the context

`close() -> None`

Close this context and all its pages.

**`context.cookies(urls?)`**

Get cookies

`cookies(urls: Optional[List[str]] = None) -> List[Cookie]`

Get cookies for this context.

CLI `vibium cookies` · MCP `browser_get_cookies`

**`context.set_cookies(cookies)`**

Set cookies

`set_cookies(cookies: List[SetCookieParam]) -> None`

Set cookies in this context.

CLI `vibium cookies <n> <v>` · MCP `browser_set_cookie`

**`context.clear_cookies()`**

Clear cookies

`clear_cookies() -> None`

Clear all cookies in this context.

CLI `vibium cookies clear` · MCP `browser_delete_cookies`

**`context.storage()`**

Get storage state

`storage() -> StorageState`

Get the storage state (cookies + localStorage + sessionStorage).

CLI `vibium storage` · MCP `browser_storage_state`

**`context.set_storage(state)`**

Set storage state

`set_storage(state: StorageState) -> None`

Set the storage state (cookies + localStorage + sessionStorage).

MCP `browser_restore_storage`

**`context.clear_storage()`**

Clear all storage

`clear_storage() -> None`

Clear all storage (cookies + localStorage + sessionStorage).

**`context.add_init_script(script)`**

Add an init script

`add_init_script(script: str) -> str`

Add an init script that runs before page scripts in this context.

**`context.id`**

User context id

`id: str  # property`

The user context ID for this browser context.

**`context.recording`**

Recording controls for the context

`recording: Recording  # property`

Get the Recording for this context.

## Keyboard

**`keyboard.press(key)`**

Press a key

`press(key: str) -> None`

Press and release a key. Supports combos like "Control+a".

Example: `vibe.keyboard.press("Enter")`

CLI `vibium keys <keys>` · MCP `browser_keys`

**`keyboard.down(key)`**

Key down

`down(key: str) -> None`

Press a key down (without releasing).

**`keyboard.up(key)`**

Key up

`up(key: str) -> None`

Release a key.

**`keyboard.type(text)`**

Type text

`type(text: str) -> None`

Type a string of text character by character.

## Mouse

**`mouse.click(x, y, **opts)`**

Click at coordinates

`click(x: float, y: float) -> None`

Click at (x, y) coordinates.

CLI `vibium mouse click <x> <y>` · MCP `browser_mouse_click`

**`mouse.move(x, y, **opts)`**

Move mouse

`move(x: float, y: float) -> None`

Move mouse to (x, y) coordinates.

CLI `vibium mouse move <x> <y>` · MCP `browser_mouse_move`

**`mouse.down(**opts)`**

Mouse button down

`down() -> None`

Press mouse button down.

CLI `vibium mouse down` · MCP `browser_mouse_down`

**`mouse.up(**opts)`**

Mouse button up

`up() -> None`

Release mouse button.

CLI `vibium mouse up` · MCP `browser_mouse_up`

**`mouse.wheel(dx, dy)`**

Scroll mouse wheel

`wheel(delta_x: float, delta_y: float) -> None`

Scroll the mouse wheel at the current pointer position.

## Touch

**`touch.tap(x, y)`**

Tap at coordinates

`tap(x: float, y: float) -> None`

Tap at (x, y) coordinates.

CLI `vibium tap <x> <y>` · MCP `browser_tap`

**`touch.swipe(direction, from_=, speed=, hold_ms=)`**

Swipe in a direction (up, down, left, right; from an edge or point; speed, hold) or between coordinates

```text
swipe(
    x1: Union[float, str],
    y1: Optional[float] = None,
    x2: Optional[float] = None,
    y2: Optional[float] = None,
    duration_ms: Optional[int] = None,
    *,
    from_: Union[str, Tuple[float, float], None] = None,
    distance: Optional[float] = None,
    speed: Union[str, float, None] = None,
    hold_ms: Optional[int] = None,
) -> None
```

Swipe in a direction, or from (x1, y1) to (x2, y2). The finger stays down for the move, so the gesture reads as a swipe/fling rather than two taps.

CLI `vibium swipe <direction>` · MCP `browser_swipe`

**`touch.long_press(x, y, duration_ms?)`**

Long-press at coordinates

`long_press(x: float, y: float, duration_ms: Optional[int] = None) -> None`

Press and hold at (x, y) for duration_ms before releasing (default 500).

CLI `vibium long-press <x> <y>` · MCP `browser_long_press`

## Clock

**`clock.install(time?, timezone?)`**

Install fake timers

`install(time: Optional[Union[int, str]] = None, timezone: Optional[str] = None) -> None`

Install fake clock, overriding Date, setTimeout, setInterval, etc.

MCP `page_clock_install`

**`clock.fast_forward(ticks)`**

Fast-forward time

`fast_forward(ticks: int) -> None`

Jump forward by ticks ms, fire each due timer at most once.

MCP `page_clock_fast_forward`

**`clock.run_for(ticks)`**

Run timers for a duration

`run_for(ticks: int) -> None`

Advance ticks ms, firing all callbacks systematically.

MCP `page_clock_run_for`

**`clock.pause_at(time)`**

Pause clock at a time

`pause_at(time: Union[int, str]) -> None`

Jump to a specific time and pause.

MCP `page_clock_pause_at`

**`clock.resume()`**

Resume clock

`resume() -> None`

Resume real-time progression from current fake time.

MCP `page_clock_resume`

**`clock.set_fixed_time(time)`**

Set fixed fake time

`set_fixed_time(time: Union[int, str]) -> None`

Freeze Date.now() at a value permanently. Timers still run.

MCP `page_clock_set_fixed_time`

**`clock.set_system_time(time)`**

Set system time

`set_system_time(time: Union[int, str]) -> None`

Set Date.now() without triggering timers.

MCP `page_clock_set_system_time`

**`clock.set_timezone(tz)`**

Set timezone

`set_timezone(timezone: str) -> None`

Override the browser timezone.

MCP `page_clock_set_timezone`

## Recording

**`recording.start(opts?)`**

Start recording

```text
start(
    name: Optional[str] = None,
    screenshots: Optional[bool] = None,
    snapshots: Optional[bool] = None,
    sources: Optional[bool] = None,
    title: Optional[str] = None,
    bidi: Optional[bool] = None,
    format: Optional[str] = None,
    quality: Optional[float] = None,
    video: Optional[Union[bool, Dict[str, Any]]] = None,
    path: Optional[str] = _UNSET,
) -> None
```

CLI `vibium record start` · MCP `browser_record_start`

**`recording.stop(path?, upload?)`**

Stop recording, return trace

`stop(path: Optional[str] = None, upload: Union[bool, str] = False) -> RecordingResult`

Stop recording and deliver the zip to the declared path.

CLI `vibium record stop` · MCP `browser_record_stop`

**`recording.start_chunk(opts?)`**

Start a recording chunk

`start_chunk(name: Optional[str] = None, title: Optional[str] = None) -> None`

Start a new recording chunk.

CLI `vibium record chunk start` · MCP `browser_record_start_chunk`

**`recording.stop_chunk(path?)`**

Stop a recording chunk

`stop_chunk(path: Optional[str] = None) -> RecordingResult`

Stop the current chunk.

CLI `vibium record chunk stop` · MCP `browser_record_stop_chunk`

**`recording.start_group(name, location?)`**

Start a logical group

`start_group(name: str, location: Optional[Dict[str, Any]] = None) -> None`

Start a named group of actions in the recording.

CLI `vibium record group start <name>` · MCP `browser_record_start_group`

**`recording.stop_group()`**

Stop a logical group

`stop_group() -> None`

End the current group.

CLI `vibium record group stop` · MCP `browser_record_stop_group`

## Route

**`route.request` (property)**

Access intercepted request

`request: Dict[str, Any]  # property`

Request info as a dict.

**`route.fulfill(status?, headers?, ...)`**

Fulfill an intercepted request

```text
fulfill(
    status: Optional[int] = None,
    headers: Optional[Dict[str, str]] = None,
    content_type: Optional[str] = None,
    body: Optional[str] = None,
) -> None
```

Fulfill the request with a custom response.

**`route.continue_(overrides?)`**

Continue an intercepted request

```text
continue_(
    url: Optional[str] = None,
    method: Optional[str] = None,
    headers: Optional[Dict[str, str]] = None,
    post_data: Optional[str] = None,
) -> None
```

Continue the request with optional overrides.

**`route.abort()`**

Abort an intercepted request

`abort() -> None`

Abort the request.

## Dialog

**`dialog.message()`**

Get dialog message

`message() -> str`

The dialog message text.

**`dialog.type()`**

Get dialog type

`type() -> str`

The dialog type: 'alert', 'confirm', 'prompt', or 'beforeunload'.

**`dialog.default_value()`**

Get dialog default value

`default_value() -> str`

The default value for prompt dialogs.

**`dialog.accept(prompt_text?)`**

Accept the dialog

`accept(prompt_text: Optional[str] = None) -> None`

Accept the dialog. For prompt dialogs, optionally provide text.

CLI `vibium dialog accept` · MCP `browser_dialog_accept`

**`dialog.dismiss()`**

Dismiss the dialog

`dismiss() -> None`

Dismiss the dialog (cancel/close).

CLI `vibium dialog dismiss` · MCP `browser_dialog_dismiss`

## Download

**`download.save_as(path)`**

Save a download to path

`save_as(path: str) -> None`

Wait for the download to complete, then save to the specified path.

**`download.url()`**

Get download URL

`url() -> str`

The URL of the download.

**`download.suggested_filename()`**

Get download filename

`suggested_filename() -> str`

The filename suggested by the server (from Content-Disposition).

**`download.path()`**

Get download path

`path() -> Optional[str]`

Wait for the download to complete and return the temp file path.

## Request

**`request.url()`**

Get request URL

`url() -> str`

The request URL.

**`request.method()`**

Get HTTP method

`method() -> str`

The HTTP method (GET, POST, etc.).

**`request.headers()`**

Get request headers

`headers() -> Dict[str, str]`

Request headers as a dict.

**`request.request_id()`**

Get BiDi request ID

`request_id() -> str`

The request ID (BiDi network request identifier).

**`request.post_data()`**

Get request body

`post_data() -> Optional[str]`

Request body / post data.

## Response

**`response.url()`**

Get response URL

`url() -> str`

The response URL.

**`response.status()`**

Get HTTP status

`status() -> int`

The HTTP status code.

**`response.headers()`**

Get response headers

`headers() -> Dict[str, str]`

Response headers as a dict.

**`response.request_id()`**

Get associated request ID

`request_id() -> str`

The request ID associated with this response.

**`response.body()`**

Get response body

`body() -> Optional[str]`

Response body as a string. Requires a data collector (set up by on_response or capture.response).

**`response.json()`**

Parse response body as JSON

`json() -> Any`

Response body parsed as JSON. Requires a data collector (set up by on_response or capture.response).

## ConsoleMessage

**`message.type()`**

Get console message type

`type() -> str`

The console method: 'log', 'warn', 'error', 'debug', 'info', etc.

**`message.text()`**

Get formatted message text

`text() -> str`

The message text.

**`message.args()`**

Get console arguments

`args() -> List[Any]`

The serialized arguments passed to the console call.

**`message.location()`**

Get source location

`location() -> Optional[Dict[str, Any]]`

The source location of the console call, if available.

## WebSocketInfo

**`socket.url()`**

Get WebSocket URL

`url() -> str`

Get the WebSocket URL.

**`socket.on_message(fn)`**

Listen for messages

`on_message(fn: Callable[[str, dict], None]) -> None`

Register handler for messages. fn(data, info) where info has 'direction'.

**`socket.on_close(fn)`**

Listen for close

`on_close(fn: Callable[[Optional[int], Optional[str]], None]) -> None`

Register handler for close. fn(code, reason).

**`socket.is_closed()`**

Check whether socket is closed

`is_closed() -> bool`

Check if the WebSocket is closed.

## Run and Check

**`browser.check(claim, record=...)`**

Independently verify the active session or a saved archive

```text
check(
    claim: str,
    *,
    record: Optional[str] = None,
    base_url: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
) -> CheckResult
```

Independently verify live behavior, or inspect a read-only archive.

CLI `vibium check <claim>` · MCP `vibium_check`

**`page.check(claim, record=...)`**

Independently verify a pinned page or a saved archive

```text
check(
    claim: str,
    *,
    record: Optional[str] = None,
    base_url: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
) -> CheckResult
```

Independently verify live behavior, or inspect a read-only archive.

**`browser.run(goal, opts?)`**

Accomplish a goal in the active browser session

```text
run(
    goal: str,
    *,
    base_url: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
) -> RunResult
```

Accomplish a live goal; the existing runtime owns the model loop.

CLI `vibium run <goal>` · MCP `vibium_run`

**`page.run(goal, opts?)`**

Accomplish a goal on a pinned page

```text
run(
    goal: str,
    *,
    base_url: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    ai_base_url: Optional[str] = None,
    reasoning_effort: Optional[str] = None,
) -> RunResult
```

Accomplish a live goal; the existing runtime owns the model loop.

## Say and Listen

**`browser.say(text, target=...)`**

Speak text into the session, this machine's speakers, or a WAV file

```text
say(
    text: str,
    *,
    file: Optional[str] = None,
    target: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    voice: Optional[str] = None,
    language: Optional[str] = None,
    speed: Optional[float] = None,
    cache: bool = True,
    cache_dir: Optional[str] = None,
) -> SayResult
```

Speak text into the current page's microphone, or into the device.

CLI `vibium say <text>` · MCP `vibium_say`

**`page.say(text, target=...)`**

Speak text into a pinned page

```text
say(
    text: str,
    *,
    file: Optional[str] = None,
    target: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    voice: Optional[str] = None,
    language: Optional[str] = None,
    speed: Optional[float] = None,
    cache: bool = True,
    cache_dir: Optional[str] = None,
) -> SayResult
```

Speak text into this page's microphone, or into the device.

**`browser.listen(target=...)`**

Hear the session, this machine's microphone, or a WAV file, and return a transcript

```text
listen(
    *,
    target: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    language: Optional[str] = None,
    silence: Optional[int] = None,
    timeout: Optional[int] = None,
    duration: Optional[int] = None,
    allow_silence: bool = False,
    path: Optional[str] = None,
    transcribe: bool = True,
) -> ListenResult
```

Hear what the current page, or the device, plays, and return its words.

CLI `vibium listen` · MCP `vibium_listen`

**`page.listen(target=...)`**

Hear a pinned page and return a transcript

```text
listen(
    *,
    target: Optional[str] = None,
    provider: Optional[str] = None,
    model: Optional[str] = None,
    language: Optional[str] = None,
    silence: Optional[int] = None,
    timeout: Optional[int] = None,
    duration: Optional[int] = None,
    allow_silence: bool = False,
    path: Optional[str] = None,
    transcribe: bool = True,
) -> ListenResult
```

Hear what this page, or the device, plays, and return its words.

## Types

Option and result types named in the signatures above.

### `A11yNode`

```python
class A11yNode(TypedDict):
    role: str
    name: str
    value: Union[str, int, float]
    description: str
    disabled: bool
    expanded: bool
    focused: bool
    checked: Union[bool, str]
    pressed: Union[bool, str]
    selected: bool
    required: bool
    readonly: bool
    level: int
    valuemin: int
    valuemax: int
    children: List[A11yNode]
```

### `BoundingBox`

```python
class BoundingBox:
    x: float
    y: float
    width: float
    height: float
```

### `CheckEvidence`

```python
class CheckEvidence(TypedDict):
    type: Literal['observation']
    summary: str
```

### `CheckResult`

```python
class CheckResult(TypedDict):
    status: Literal['passed', 'failed', 'inconclusive']
    claim: str
    summary: str
    reason: NotRequired[Literal['action_limit', 'insufficient_evidence', 'safety_stop', 'archive_missing_evidence']]
    evidence: List[CheckEvidence]
```

### `Cookie`

```python
class Cookie(TypedDict):
    name: str
    value: str
    domain: str
    path: str
    size: int
    httpOnly: bool
    secure: bool
    sameSite: str
    expiry: int
```

### `ImageInput`

```python
ImageInput = Union[str, bytes, bytearray, memoryview, 'os.PathLike[str]']
```

### `ListenResult`

```python
class ListenResult:
    text: str
    transcribed: bool
    speech: bool
    stopped_by: str
    duration_ms: float
    target: str
    provider: str
    model: str
    segments: List[Segment] = field(default_factory=list)
    words: Optional[List[Word]] = None
    onset_ms: Optional[float] = None
    speech_end_ms: Optional[float] = None
    latency_ms: Optional[float] = None
    path: Optional[str] = None
    lost_ms: Optional[float] = None
```

### `OriginState`

```python
class OriginState(TypedDict):
    origin: str
    localStorage: List[_StorageEntry]
    sessionStorage: List[_StorageEntry]
```

### `RecordingResult`

```python
class RecordingResult:
    path: Optional[str] = None
    data: Optional[bytes] = None
    steps: Optional[int] = None
    duration_ms: Optional[int] = None
    videos: List[Dict[str, Any]] = field(default_factory=list)
    video_unavailable: Optional[str] = None
    upload: Optional[Dict[str, Any]] = None
```

### `RunResult`

```python
class RunResult(TypedDict):
    status: Literal['completed', 'not_completed']
    goal: str
    summary: str
    reason: NotRequired[Literal['action_limit', 'missing_information', 'safety_stop']]
    evidence: List[CheckEvidence]
```

### `SayResult`

```python
class SayResult:
    text: str
    target: str
    provider: str
    model: str
    voice: str
    duration_ms: float
    cached: bool
    sha256: str
    path: Optional[str] = None
    file: Optional[str] = None
```

### `Segment`

```python
class Segment:
    start_ms: float
    end_ms: float
    text: str
```

### `SetCookieParam`

```python
class SetCookieParam(TypedDict):
    name: str
    value: str
    domain: str
    url: str
    path: str
    httpOnly: bool
    secure: bool
    sameSite: str
    expiry: int
```

### `StorageState`

```python
class StorageState(TypedDict):
    cookies: List[Cookie]
    origins: List[OriginState]
```

### `Word`

```python
class Word:
    start_ms: float
    end_ms: float
    word: str
```
