Skip to main content
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: 
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: 
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: 
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: 
cmux browser surface:1 snapshot

​
browser eval

Evaluate JavaScript in the page context. 
cmux browser <surface> eval [--script <js>] <javascript>
Examples: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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: 
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