cmux-browser

Source excerpt starting at line 1.

1# Command Reference (cmux Browser)2 3## Surface contract4 5Run `cmux browser --help` against the installed binary before relying on exact6syntax. Creation verbs (`open`, `open-split`, `new`) and the explicitly global7browser verbs listed in `SKILL.md` may omit a surface. Every surface-bound8command that reads or mutates an existing browser must include one:9 10```bash11cmux browser --surface <surface> get url12cmux browser --surface <surface> snapshot --interactive13cmux browser --surface <surface> tab list14cmux browser --surface <surface> click <selector-or-ref>15```16 17`cmux browser <surface> <verb> ...` is the equivalent positional form. See18[surface-discovery.md](surface-discovery.md) before targeting an existing19authenticated browser or a browser in another workspace.20 21## Accepted aliases22 23Use the preferred column in new docs/scripts; every alias still requires the24same explicit surface.25 26| Purpose | Preferred | Accepted alias |27| --- | --- | --- |28| Read URL | `cmux browser --surface <surface> get url` | `cmux browser --surface <surface> url` or `get-url` |29| Navigate | `cmux browser --surface <surface> goto <url>` | `navigate` |30| Interactive snapshot | `cmux browser --surface <surface> snapshot --interactive` | `-i` |31| Press a key | `cmux browser --surface <surface> press <key>` | `key` |32 33The upstream `agent-browser` command's implicit page context maps to an34explicit cmux surface. Its interactive snapshot maps to `snapshot35--interactive`; its `open` command maps to `cmux browser open` because creation36returns a new surface.37 38## Discovery and creation39 40```bash41cmux identify --json42cmux tree --all --json43cmux browser --surface <surface> identify --json44 45cmux --json browser open <url> --focus false46cmux --json browser open <url> --workspace <workspace> --window <window> --focus false47cmux --json browser open-split <url> --workspace <workspace> --focus false48```49 50Creation defaults to the caller's `CMUX_WORKSPACE_ID` when neither51`--workspace` nor `--window` is supplied, and `--focus` defaults to false. An52explicit `--workspace` lets an agent create in another workspace without53selecting it.54 55## Navigation56 57```bash58cmux browser --surface <surface> goto <url>59cmux browser --surface <surface> back|forward|reload60cmux browser --surface <surface> get url|title61```62 63## Snapshot and inspection64 65```bash66cmux browser --surface <surface> snapshot --interactive67cmux browser --surface <surface> snapshot --interactive --compact --max-depth 368cmux browser --surface <surface> get text body69cmux browser --surface <surface> get html body70cmux browser --surface <surface> get value "#email"71cmux browser --surface <surface> get attr "#email" --attr placeholder72cmux browser --surface <surface> get count ".row"73cmux browser --surface <surface> get box "#submit"74cmux browser --surface <surface> get styles "#submit" --property color75cmux browser --surface <surface> eval '<js>'76```77 78## Interaction79 80```bash81cmux browser --surface <surface> click|dblclick|hover|focus <selector-or-ref>82cmux browser --surface <surface> fill <selector-or-ref> [text]83cmux browser --surface <surface> type <selector-or-ref> <text>84cmux browser --surface <surface> press|key|keydown|keyup [--key <key> | <key>]85cmux browser --surface <surface> select <selector-or-ref> <value>86cmux browser --surface <surface> check|uncheck <selector-or-ref>87cmux browser --surface <surface> scroll [--selector <css>] [--dx <n>] [--dy <n>]88```89 90Empty `fill` text clears the field. Keyboard names follow Playwright/W3C91conventions (`Enter`, `Tab`, `Escape`, `ArrowLeft`, `Space`). Supported keys92use the native WebKit input path, preserving browser defaults such as93contenteditable caret movement, selection, scrolling, and control activation;94opaque tokens use a page-event compatibility fallback. `Space`, `Spacebar`,95and `space` emit DOM key `" "` with code `"Space"`; use `--key ' '` to pass96the raw DOM key. Use `keydown Shift`/`keyup Shift` (or another supported97modifier) around an arrow press when a page editor should extend a selection;98the modifier state is retained per browser surface.99 100## Wait101 102```bash103cmux browser --surface <surface> wait --selector "#ready" --timeout-ms 10000104cmux browser --surface <surface> wait --text "Done" --timeout-ms 10000105cmux browser --surface <surface> wait --url-contains "/dashboard" --timeout-ms 10000106cmux browser --surface <surface> wait --load-state complete --timeout-ms 15000107cmux browser --surface <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000108```109 110## Design mode111 112```bash113cmux browser --surface <surface> design-mode enable|status|disable --json114```115 116Design mode lets a user select page elements and copy their DOM, style, URL,117and screenshot context for pasting into an agent. CLI enable/disable never118moves application focus or copies context automatically.119 120## Session, state, and diagnostics121 122```bash123cmux browser --surface <surface> cookies get|set|clear ...124cmux browser --surface <surface> cookies clear --url https://app.example.com/125cmux browser --surface <surface> cookies clear --domain app.example.com126cmux browser --surface <surface> cookies clear --all127cmux browser --surface <surface> storage local|session get|set|clear ...128cmux browser --surface <surface> tab list|new|switch|close ...129cmux browser --surface <surface> state save|load <path>130cmux browser --surface <surface> console list|clear131cmux browser --surface <surface> errors list|clear132cmux browser --surface <surface> highlight <selector>133cmux browser --surface <surface> screenshot134cmux browser --surface <surface> download list [--limit <1...25>]135cmux browser --surface <surface> download wait --timeout-ms 10000136```137 138`download list` returns the newest records for that browser surface without139consuming `download wait` events. JSON records include `download_id`,140`filename`, the actual saved `path` (or `null`), `status`, `bytes` when known,141and `path_exists` when a path is present. The list is capped at 25 records;142`--limit` may request a smaller positive count. Text output marks unavailable143values explicitly.144The legacy positional form treats a bare token as a destination path, so use145the explicit `download wait <path>` or `download --path <path>` spelling when146you want to make that intent unambiguous. `download list` is the only listing147subcommand.148 149`cookies clear` requires an explicit scope (`--url`, `--domain`, `--name`,150`--path`, another cookie filter, or `--all`). URL scope follows cookie151domain/path, secure, and expiration matching for the requested URL. JSON152responses include the number of removed cookies as `cleared`.153 154## Agent reliability155 156Use `--snapshot-after` on mutating actions to get a fresh post-action snapshot.157Re-snapshot after navigation, modal open/close, or major DOM changes. Prefer158short handles in output; use `--id-format both` only when a UUID must be logged159or exported. If the handle is stale, rediscover it; never silently retarget the160focused browser.161 162## Viewport emulation163 164```bash165cmux browser --surface <surface> viewport 1280 720166cmux browser --surface <surface> screenshot --out /tmp/desktop.png167cmux browser --surface <surface> viewport reset168```169 170Dimensions are limited to 1..4096 CSS pixels. cmux changes171`window.innerWidth`/`window.innerHeight` and aspect-fits the page inside the172existing pane; it does not resize the pane, move other surfaces, or change173focus. Screenshot PNG dimensions are exact CSS pixels on Retina and non-Retina174displays.175 176An unsupported viewport/page-zoom combination leaves the viewport unchanged177and returns `invalid_params` with reason178`viewport_zoom_render_geometry_too_large` plus `maximum_page_zoom`. An attached179browser inspector returns `invalid_state` with reason180`attached_browser_inspector`; close or detach it first. Opening or redocking an181attached inspector while emulation is active resets the viewport to native182sizing.183 184## Known WKWebView gaps (`not_supported`)185 186`browser.geolocation.set`, `browser.offline.set`, `browser.trace.start|stop`,187`browser.network.route|unroute|requests`, `browser.screencast.start|stop`, and188`browser.input_mouse|input_keyboard|input_touch` are not supported by the189WKWebView engine.190 191See also [snapshot-refs.md](snapshot-refs.md),192[authentication.md](authentication.md), and193[session-management.md](session-management.md).194