#Browser Automation

The Coterm browser command group provides browser automation against Coterm browser surfaces. Use it to navigate, interact with DOM elements, inspect page state, evaluate JavaScript, and manage browser session data.

#Command Index

Category	Subcommands
Navigation and targeting	`identify`, `open`, `open-split`, `navigate`, `back`, `forward`, `reload`, `url`, `focus-webview`, `is-webview-focused`, `zoom`, `focus-mode`, `react-grab`, `devtools`
Waiting	`wait`
DOM interaction	`click`, `dblclick`, `hover`, `focus`, `check`, `uncheck`, `scroll-into-view`, `type`, `fill`, `press`, `keydown`, `keyup`, `select`, `scroll`
Inspection	`snapshot`, `screenshot`, `get`, `is`, `find`, `highlight`
JavaScript and injection	`eval`, `addinitscript`, `addscript`, `addstyle`
Frames, dialogs, downloads	`frame`, `dialog`, `download`
State and session data	`cookies`, `storage`, `state`, `history`
Tabs and logs	`tab`, `console`, `errors`

#Targeting a browser surface

Most subcommands require a target surface. You can pass it positionally or with --surface.

# Open a new browser split
Coterm browser open https://example.com

# Discover focused IDs and browser metadata
Coterm browser identify
Coterm browser identify --surface surface:2

# Positional vs flag targeting are equivalent
Coterm browser surface:2 url
Coterm browser --surface surface:2 url

Coterm browser open https://example.com
Coterm browser open-split https://news.ycombinator.com

Coterm browser surface:2 navigate https://example.org/docs --snapshot-after
Coterm browser surface:2 back
Coterm browser surface:2 forward
Coterm browser surface:2 reload --snapshot-after
Coterm browser surface:2 url

Coterm browser surface:2 focus-webview
Coterm browser surface:2 is-webview-focused

Coterm browser react-grab toggle
Coterm browser devtools toggle
Coterm browser devtools console
Coterm browser focus-mode toggle
Coterm browser zoom in
Coterm browser zoom reset
Coterm browser history clear --force

#Waiting

Use wait to block until selectors, text, URL fragments, load state, or a JavaScript condition is satisfied.

Coterm browser surface:2 wait --load-state complete --timeout-ms 15000
Coterm browser surface:2 wait --selector "#checkout" --timeout-ms 10000
Coterm browser surface:2 wait --text "Order confirmed"
Coterm browser surface:2 wait --url-contains "/dashboard"
Coterm browser surface:2 wait --function "window.__appReady === true"

#DOM Interaction

Mutating actions support --snapshot-after for fast verification in scripts.

Coterm browser surface:2 click "button[type='submit']" --snapshot-after
Coterm browser surface:2 dblclick ".item-row"
Coterm browser surface:2 hover "#menu"
Coterm browser surface:2 focus "#email"
Coterm browser surface:2 check "#terms"
Coterm browser surface:2 uncheck "#newsletter"
Coterm browser surface:2 scroll-into-view "#pricing"

Coterm browser surface:2 type "#search" "coterm"
Coterm browser surface:2 fill "#email" --text "ops@example.com"
Coterm browser surface:2 fill "#email" --text ""
Coterm browser surface:2 press Enter
Coterm browser surface:2 keydown Shift
Coterm browser surface:2 keyup Shift
Coterm browser surface:2 select "#region" "us-east"
Coterm browser surface:2 scroll --dy 800 --snapshot-after
Coterm browser surface:2 scroll --selector "#log-view" --dx 0 --dy 400

#Inspection

Use structured getters for scripts and snapshots/screenshots for human review.

Coterm browser surface:2 snapshot --interactive --compact
Coterm browser surface:2 snapshot --selector "main" --max-depth 5
Coterm browser surface:2 screenshot --out /tmp/coterm-page.png

Coterm browser surface:2 get title
Coterm browser surface:2 get url
Coterm browser surface:2 get text "h1"
Coterm browser surface:2 get html "main"
Coterm browser surface:2 get value "#email"
Coterm browser surface:2 get attr "a.primary" --attr href
Coterm browser surface:2 get count ".row"
Coterm browser surface:2 get box "#checkout"
Coterm browser surface:2 get styles "#total" --property color

Coterm browser surface:2 is visible "#checkout"
Coterm browser surface:2 is enabled "button[type='submit']"
Coterm browser surface:2 is checked "#terms"

Coterm browser surface:2 find role button --name "Continue"
Coterm browser surface:2 find text "Order confirmed"
Coterm browser surface:2 find label "Email"
Coterm browser surface:2 find placeholder "Search"
Coterm browser surface:2 find alt "Product image"
Coterm browser surface:2 find title "Open settings"
Coterm browser surface:2 find testid "save-btn"
Coterm browser surface:2 find first ".row"
Coterm browser surface:2 find last ".row"
Coterm browser surface:2 find nth 2 ".row"

Coterm browser surface:2 highlight "#checkout"

#JavaScript Eval and Injection

Coterm browser surface:2 eval "document.title"
Coterm browser surface:2 eval --script "window.location.href"

Coterm browser surface:2 addinitscript "window.__cotermReady = true;"
Coterm browser surface:2 addscript "document.querySelector('#name')?.focus()"
Coterm browser surface:2 addstyle "#debug-banner { display: none !important; }"

#State

Session data commands cover cookies, local/session storage, and full browser state snapshots.

Coterm browser surface:2 cookies get
Coterm browser surface:2 cookies get --name session_id
Coterm browser surface:2 cookies set session_id abc123 --domain example.com --path /
Coterm browser surface:2 cookies clear --name session_id
Coterm browser surface:2 cookies clear --all

Coterm browser surface:2 storage local set theme dark
Coterm browser surface:2 storage local get theme
Coterm browser surface:2 storage local clear
Coterm browser surface:2 storage session set flow onboarding
Coterm browser surface:2 storage session get flow

Coterm browser surface:2 state save /tmp/coterm-browser-state.json
Coterm browser surface:2 state load /tmp/coterm-browser-state.json

#Tabs

Browser tab operations map to browser surfaces in the active browser tab group.

Coterm browser surface:2 tab list
Coterm browser surface:2 tab new https://example.com/pricing

# Switch by index or by target surface
Coterm browser surface:2 tab switch 1
Coterm browser surface:2 tab switch surface:7

# Close current tab or a specific target
Coterm browser surface:2 tab close
Coterm browser surface:2 tab close surface:7

#Console and Errors

Coterm browser surface:2 console list
Coterm browser surface:2 console clear

Coterm browser surface:2 errors list
Coterm browser surface:2 errors clear

#Dialogs

Coterm browser surface:2 dialog accept
Coterm browser surface:2 dialog accept "Confirmed by automation"
Coterm browser surface:2 dialog dismiss

#Frames

# Enter an iframe context
Coterm browser surface:2 frame "iframe[name='checkout']"
Coterm browser surface:2 click "#pay-now"

# Return to the top-level document
Coterm browser surface:2 frame main

#Downloads

Coterm browser surface:2 click "a#download-report"
Coterm browser surface:2 download --path /tmp/report.csv --timeout-ms 30000

#Common Patterns

#Navigate, wait, inspect

Coterm browser open https://example.com/login
Coterm browser surface:2 wait --load-state complete --timeout-ms 15000
Coterm browser surface:2 snapshot --interactive --compact
Coterm browser surface:2 get title

#Fill a form and verify success text

Coterm browser surface:2 fill "#email" --text "ops@example.com"
Coterm browser surface:2 fill "#password" --text "$PASSWORD"
Coterm browser surface:2 click "button[type='submit']" --snapshot-after
Coterm browser surface:2 wait --text "Welcome"
Coterm browser surface:2 is visible "#dashboard"

#Capture debug artifacts on failure

Coterm browser surface:2 console list
Coterm browser surface:2 errors list
Coterm browser surface:2 screenshot --out /tmp/coterm-failure.png
Coterm browser surface:2 snapshot --interactive --compact

#Persist and restore browser session

Coterm browser surface:2 state save /tmp/session.json
# ...later...
Coterm browser surface:2 state load /tmp/session.json
Coterm browser surface:2 reload