Browser Commands

Control embedded browser surfaces with CLI automation

Control browser surfaces in cmux for web automation. All browser commands use the browser namespace or legacy aliases.

browser identify

Get information about a browser surface including URL and title.

cmux browser [surface] identify

Example:

cmux browser surface:1 identify

Output (JSON with —json):

{
  "browser": {
    "surface": "surface:1",
    "url": "https://example.com",
    "title": "Example Domain"
  }
}

browser open / open-split

Open a URL in a new or existing browser surface.

cmux browser open [--workspace <id>] [--window <id>] [url]
cmux browser open-split [--workspace <id>] [url]

Flags:

--workspace · string

Workspace context (defaults to $CMUX_WORKSPACE_ID)

--window · string

Window context for routing

Examples:

Open URL

cmux browser open https://github.com

Output:

OK surface=surface:2 pane=pane:1 placement=split

browser navigate / goto

Navigate a browser surface to a URL.

cmux browser <surface> navigate <url> [--snapshot-after]

Flags:

--snapshot-after · boolean

Capture page snapshot after navigation completes

Examples:

Navigate

cmux browser surface:1 navigate https://example.com

Output:

OK

browser back / forward / reload

Navigate browser history or reload the page.

cmux browser <surface> back [--snapshot-after]
cmux browser <surface> forward [--snapshot-after]
cmux browser <surface> reload [--snapshot-after]

Examples:

Back

cmux browser surface:1 back

browser url / get-url

Get the current URL of a browser surface.

cmux browser <surface> url
cmux browser <surface> get-url

Example:

cmux browser surface:1 url

Output:

https://example.com

browser snapshot

Capture a text snapshot of the page DOM.

cmux browser <surface> snapshot [--selector <css>] [--max-depth <n>] [--interactive] [--cursor] [--compact]

Flags:

--selector · string

CSS selector to snapshot (defaults to entire page)

--max-depth · number

Maximum DOM depth to traverse

--interactive · boolean

Include interactive elements only

-i · boolean

Alias for --interactive

--cursor · boolean

Include cursor position indicators

--compact · boolean

Use compact output format

Examples:

Full Page

cmux browser surface:1 snapshot

browser eval

Evaluate JavaScript in the page context.

cmux browser <surface> eval [--script <js>] <javascript>

Examples:

Simple Expression

cmux browser surface:1 eval "document.title"

Output: Returns the evaluated value as text or JSON.

browser wait

Wait for a condition to be met on the page.

cmux browser <surface> wait [--selector <css>] [--text <text>] [--url-contains <text>] [--load-state <state>] [--function <js>] [--timeout <seconds>]

Flags:

--selector · string

CSS selector to wait for

--text · string

Wait for element containing text

--url-contains · string

Wait for URL to contain text

--url · string

Alias for --url-contains

--load-state · string

Wait for load state: load, domcontentloaded, networkidle

--function · string

JavaScript function that returns truthy when condition is met

--timeout · number

Timeout in seconds (default varies by condition)

--timeout-ms · number

Timeout in milliseconds

Examples:

Wait for Selector

cmux browser surface:1 wait --selector ".loaded"

browser click / dblclick / hover

Interact with page elements.

cmux browser <surface> click [--selector <css>] <selector> [--snapshot-after]
cmux browser <surface> dblclick [--selector <css>] <selector> [--snapshot-after]
cmux browser <surface> hover [--selector <css>] <selector> [--snapshot-after]

Examples:

Click

cmux browser surface:1 click "button#submit"

browser type / fill

Type text into input fields.

cmux browser <surface> type [--selector <css>] <selector> [--text <text>] <text> [--snapshot-after]
cmux browser <surface> fill [--selector <css>] <selector> [--text <text>] <text> [--snapshot-after]

Note: type requires text, fill allows empty string to clear.

Examples:

Type Text

cmux browser surface:1 type "input#search" "query text"

browser press / key / keydown / keyup

Simulate keyboard input.

cmux browser <surface> press [--key <key>] <key> [--snapshot-after]
cmux browser <surface> key [--key <key>] <key>
cmux browser <surface> keydown <key>
cmux browser <surface> keyup <key>

Examples:

Press Enter

cmux browser surface:1 press Enter

browser check / uncheck

Toggle checkboxes.

cmux browser <surface> check <selector> [--snapshot-after]
cmux browser <surface> uncheck <selector> [--snapshot-after]

Examples:

cmux browser surface:1 check "input[type='checkbox']#terms"
cmux browser surface:1 uncheck "#newsletter"

browser select

Select a dropdown option.

cmux browser <surface> select [--selector <css>] <selector> [--value <value>] <value> [--snapshot-after]

Example:

cmux browser surface:1 select "select#country" "US"

browser scroll

Scroll the page or an element.

cmux browser <surface> scroll [--selector <css>] [--dx <pixels>] [--dy <pixels>] [dy] [--snapshot-after]

Flags:

--selector · string

Element to scroll (defaults to page)

--dx · number

Horizontal scroll amount in pixels

--dy · number

Vertical scroll amount in pixels (can be positional)

Examples:

Scroll Down

cmux browser surface:1 scroll --dy 500

browser scrollintoview / scroll-into-view

Scroll an element into view.

cmux browser <surface> scrollintoview <selector> [--snapshot-after]

Example:

cmux browser surface:1 scrollintoview "#footer"

browser focus

Focus a page element.

cmux browser <surface> focus <selector> [--snapshot-after]

Example:

cmux browser surface:1 focus "input#email"

browser focus-webview

Focus the browser’s webview (give keyboard control to the page).

cmux browser <surface> focus-webview

browser is-webview-focused

Check if the browser’s webview has focus.

cmux browser <surface> is-webview-focused

Output:

true

browser screenshot

Capture a PNG screenshot of the page.

cmux browser <surface> screenshot [--out <path>]

Flags:

--out · string

Output file path for PNG screenshot

Examples:

To File

cmux browser surface:1 screenshot --out page.png

Output:

OK page.png

browser get

Extract data from page elements.

cmux browser <surface> get <subcommand> [options]

Subcommands:

get url

cmux browser surface:1 get url

get title

cmux browser surface:1 get title

get text

cmux browser surface:1 get text [--selector] <selector>

get html

cmux browser surface:1 get html [--selector] <selector>

get value

cmux browser surface:1 get value [--selector] <selector>

get attr

cmux browser surface:1 get attr [--selector] <selector> --attr <name>

Example:

cmux browser surface:1 get attr "a.link" --attr href

get count

cmux browser surface:1 get count [--selector] <selector>

get box

cmux browser surface:1 get box [--selector] <selector>

Returns bounding box coordinates.

get styles

cmux browser surface:1 get styles [--selector] <selector> [--property <name>]

Examples:

Get Text

cmux browser surface:1 get text "h1"

browser is

Check element state.

cmux browser <surface> is <subcommand> [--selector] <selector>

Subcommands:

• visible - Check if element is visible
• enabled - Check if element is enabled
• checked - Check if checkbox/radio is checked

Examples:

Is Visible

cmux browser surface:1 is visible ".modal"

Output:

true

browser find

Find elements using various locator strategies.

cmux browser <surface> find <locator> [options]

Locators:

find role

cmux browser surface:1 find role <role> [--name <text>] [--exact]

Example:

cmux browser surface:1 find role button --name "Submit"

find text / label / placeholder / alt / title / testid

cmux browser surface:1 find text <text> [--exact]
cmux browser surface:1 find label <text> [--exact]
cmux browser surface:1 find placeholder <text> [--exact]

Example:

cmux browser surface:1 find text "Click here" --exact

find first / last

cmux browser surface:1 find first [--selector] <selector>
cmux browser surface:1 find last [--selector] <selector>

find nth

cmux browser surface:1 find nth [--index] <index> [--selector] <selector>

Example:

cmux browser surface:1 find nth --index 2 --selector "li"

browser frame

Switch to an iframe context.

cmux browser <surface> frame <selector>
cmux browser <surface> frame main

Examples:

Select Frame

cmux browser surface:1 frame "iframe#content"

browser dialog

Handle JavaScript dialogs (alert/confirm/prompt).

cmux browser <surface> dialog accept [text]
cmux browser <surface> dialog dismiss

Examples:

Accept Alert

cmux browser surface:1 dialog accept

browser download

Wait for a download to complete.

cmux browser <surface> download [wait] [--path <path>] [--timeout <seconds>] [--timeout-ms <ms>]

Flags:

--path · string

Expected download path

--timeout · number

Timeout in seconds

--timeout-ms · number

Timeout in milliseconds

Example:

cmux browser surface:1 download --path ~/Downloads/file.pdf --timeout 30

browser cookies

Manage browser cookies.

cmux browser <surface> cookies <get|set|clear> [options]

cookies get

cmux browser surface:1 cookies get [--name <name>] [--all]

cookies set

cmux browser surface:1 cookies set <name> <value> [--domain <domain>] [--path <path>] [--secure] [--expires <timestamp>]

cookies clear

cmux browser surface:1 cookies clear [--name <name>]

Examples:

Get All Cookies

cmux browser surface:1 cookies get --all

browser storage

Manage localStorage and sessionStorage.

cmux browser <surface> storage <local|session> <get|set|clear> [key] [value]

Examples:

Get Item

cmux browser surface:1 storage local get myKey

browser tab

Manage browser tabs (within the surface).

cmux browser <surface> tab <list|new|switch|close> [options]

tab list

cmux browser surface:1 tab list

tab new

cmux browser surface:1 tab new [url]

tab switch

cmux browser surface:1 tab switch <index|surface_id>

tab close

cmux browser surface:1 tab close <index|surface_id>

browser console

View or clear console messages.

cmux browser <surface> console [list|clear]

Examples:

List Console

cmux browser surface:1 console list

Output:

[log] Page loaded
[warn] Deprecated API used
[error] Failed to fetch resource

browser errors

View or clear page errors.

cmux browser <surface> errors [list|clear]

Example:

cmux browser surface:1 errors list

browser highlight

Highlight an element on the page (visual debugging).

cmux browser <surface> highlight [--selector] <selector>

Example:

cmux browser surface:1 highlight ".submit-button"

browser state

Save or load browser state.

cmux browser <surface> state save <path>
cmux browser <surface> state load <path>

Examples:

Save State

cmux browser surface:1 state save ~/browser-state.json

browser addinitscript / addscript / addstyle

Inject scripts or styles into pages.

cmux browser <surface> addinitscript [--script <js>] <javascript>
cmux browser <surface> addscript [--script <js>] <javascript>
cmux browser <surface> addstyle [--css <css>] <css>

Examples:

Add Init Script

cmux browser surface:1 addinitscript "console.log('Page loading')"

browser viewport

Set the viewport size.

cmux browser <surface> viewport <width> <height>

Example:

cmux browser surface:1 viewport 1920 1080

browser geolocation / geo

Set geolocation coordinates.

cmux browser <surface> geolocation <latitude> <longitude>

Example:

cmux browser surface:1 geolocation 37.7749 -122.4194

browser offline

Simulate offline mode.

cmux browser <surface> offline <true|false>

Example:

cmux browser surface:1 offline true

browser trace

Start or stop tracing.

cmux browser <surface> trace start [path]
cmux browser <surface> trace stop [path]

Example:

cmux browser surface:1 trace start ~/trace.json
cmux browser surface:1 trace stop

browser network

Manage network routes and requests.

cmux browser <surface> network route <pattern> [--abort] [--body <text>]
cmux browser <surface> network unroute <pattern>
cmux browser <surface> network requests

Examples:

Route Pattern

cmux browser surface:1 network route "**/api/**" --body '{"mocked":true}'

browser screencast

Start or stop video recording.

cmux browser <surface> screencast start
cmux browser <surface> screencast stop

browser input

Low-level input simulation.

cmux browser <surface> input mouse [args]
cmux browser <surface> input keyboard [args]
cmux browser <surface> input touch [args]

Legacy Aliases

These legacy commands are aliased to the browser namespace:

• open-browser → browser open
• navigate → browser navigate
• browser-back → browser back
• browser-forward → browser forward
• browser-reload → browser reload
• get-url → browser get-url
• focus-webview → browser focus-webview
• is-webview-focused → browser is-webview-focused

Note: --panel is accepted as a legacy alias for --surface in all browser commands.

Global Flags

--socket · string

Path to the cmux socket (default: /tmp/cmux.sock or $CMUX_SOCKET_PATH)

--password · string

Socket authentication password (or use $CMUX_SOCKET_PASSWORD)

--json · boolean

Output results in JSON format

--id-format · string

Control ID output format: refs, uuids, or both