DocsAutomation

Browser CLI Reference

Complete reference for the dev browser automation commands

Overview#

The dev browser command lets AI agents and users control Agentastic's built-in browser from the terminal. It communicates with the app over a Unix domain socket using JSON-RPC.

All commands follow the pattern:

bash

dev browser [--browser-id <id>] [--intent <text>] <command> [args...]

Environment#

Variable	Required	Description
`AGENTASTIC_SOCKET_PATH`	Yes	Path to the Unix domain socket. Set automatically in Agentastic terminals.
`AGENTASTIC_BROWSER_ID`	No	Default browser tab ID. Avoids passing `--browser-id` on every command.
`AGENTASTIC_AGENT_PROVIDER`	No	Agent name shown beside the on-screen cursor. Set automatically for agent terminals.

Global Flags#

Flag	Description
`--browser-id <id>`	Override browser tab ID for this invocation
`--intent <text>`	Describe why you are running this command. Shown in the tooltip beside the agent cursor. Accepted anywhere in the argument list.
`--help`	Show help message
`--version`	Show version

Agent Presence#

When a browser tab is visible on screen, Agentastic draws a cursor for the agent driving it. The cursor arcs to each element before the action fires, pulses on click, and carries a tooltip naming the agent and what it is doing. The URL bar picks up the accent color for as long as the agent is active, and drops it after a minute of inactivity or when the agent calls done.

None of this is injected into the page: the cursor is drawn by the app, so it never appears in snapshot, get html, or screenshot output, and it survives navigations.

Tooltip text is resolved in this order:

--intent on the command
A description derived from the command and the target element's accessible name
The session description set by task

Presence costs nothing when nobody is watching — for tabs in background editor tabs, and for the offscreen tabs agent sessions normally use, the whole layer is skipped.

Element Selectors#

Commands that take a <selector> argument accept either:

CSS selectors — e.g., #login-btn, .nav a, input[name=email]
@eN references — e.g., @e1, @e5 — assigned by the snapshot command

Commands#

Snapshot and Inspection#

`snapshot`#

Take an accessibility snapshot of the page. Returns a tree of elements with roles, names, and @eN references.

bash

dev browser snapshot

Output:

code

heading 'My App' @e1
  navigation 'Main'
    link 'Home' @e2
    link 'About' @e3
  textbox 'Search...' @e4
  button 'Sign In' @e5

`screenshot`#

Take a screenshot of the page. By default saves a PNG file and prints the path.

bash

dev browser screenshot                    # Saves to /tmp and prints path
dev browser screenshot -o ./shot.png      # Save to specific file
dev browser screenshot --raw              # Returns base64-encoded PNG

`highlight <selector>`#

Highlight an element with a red dashed outline for 2 seconds. Useful for visual debugging.

bash

dev browser highlight "@e5"
dev browser highlight "#main-content"

Actions#

`click <selector>`#

Click an element. Scrolls it into view first.

bash

dev browser click "@e5"
dev browser click "#submit-btn"

`dblclick <selector>`#

Double-click an element.

bash

dev browser dblclick "@e3"

`fill <selector> <value>`#

Clear a field and set its value. Works with React controlled inputs.

bash

dev browser fill "@e4" "hello@example.com"
dev browser fill "input[name=password]" "secret123"

`type <selector> <text>`#

Type text character by character into an element (fires keydown/input/keyup for each character). Use this when fill doesn't trigger the right events.

bash

dev browser type "@e4" "search query"

`press <selector> <key>`#

Press a key on an element (dispatches keydown, keypress, keyup). Supports modifier keys.

bash

dev browser press "@e4" "Enter"
dev browser press "@e4" "Tab"

`keydown <selector> <key>`#

Dispatch only a keydown event on an element.

bash

dev browser keydown "@e4" "Shift"
dev browser keydown "@e4" "ArrowDown"

`keyup <selector> <key>`#

Dispatch only a keyup event on an element.

bash

dev browser keyup "@e4" "Shift"

`hover <selector>`#

Hover over an element (fires mouseenter/mouseover).

bash

dev browser hover "@e3"

`focus <selector>`#

Focus an element.

bash

dev browser focus "@e4"

`check <selector>`#

Check a checkbox.

bash

dev browser check "@e6"

`uncheck <selector>`#

Uncheck a checkbox.

bash

dev browser uncheck "@e6"

`select <selector> <value>`#

Select an option in a <select> dropdown.

bash

dev browser select "#country" "US"

`scroll <x> <y> [selector]`#

Scroll by x,y pixels. Optionally within a specific element.

bash

dev browser scroll 0 500           # Scroll page down 500px
dev browser scroll 0 -200 ".panel" # Scroll element up 200px

`scroll_into_view <selector>`#

Scroll an element into the visible viewport.

bash

dev browser scroll_into_view "@e10"

`eval <javascript>`#

Evaluate JavaScript in the page context. Returns the result.

bash

dev browser eval "document.title"
dev browser eval "document.querySelectorAll('button').length"
dev browser eval "localStorage.getItem('token')"

`focus_webview`#

Make the WKWebView the first responder (gives keyboard focus to the browser).

bash

dev browser focus_webview

`is_webview_focused`#

Check whether the WKWebView currently has keyboard focus.

bash

dev browser is_webview_focused

`navigate <url>`#

Navigate to a URL.

bash

dev browser navigate "https://example.com"
dev browser navigate "http://localhost:3000/dashboard"

`back`#

Go back in browser history.

bash

dev browser back

`forward`#

Go forward in browser history.

bash

dev browser forward

`reload`#

Reload the current page.

bash

dev browser reload

Wait#

All wait commands support an optional --timeout <ms> flag (default varies by command).

`wait selector <selector> [--timeout <ms>]`#

Wait for an element matching the selector to appear in the DOM.

bash

dev browser wait selector ".loaded"
dev browser wait selector "#results" --timeout 10000

`wait text <text> [--timeout <ms>]`#

Wait for text to appear anywhere on the page.

bash

dev browser wait text "Welcome back"
dev browser wait text "Success" --timeout 5000

`wait url <pattern> [--timeout <ms>]`#

Wait for the page URL to contain a substring.

bash

dev browser wait url "/dashboard"
dev browser wait url "success=true" --timeout 5000

`wait load [--timeout <ms>]`#

Wait for the page to finish loading (document.readyState === 'complete').

bash

dev browser wait load
dev browser wait load --timeout 15000

Get#

`get url`#

Get the current page URL.

bash

dev browser get url

`get title`#

Get the current page title.

bash

dev browser get title

`get text [selector]`#

Get text content. Without a selector, returns the full page text.

bash

dev browser get text             # Full page text
dev browser get text ".hero h1"  # Specific element
dev browser get text "@e3"       # By reference

`get html [selector]`#

Get HTML content. Without a selector, returns the full page HTML.

bash

dev browser get html ".content"

`get value <selector>`#

Get the value of a form input.

bash

dev browser get value "input[name=email]"
dev browser get value "@e4"

`get attr <selector> <attribute>`#

Get an HTML attribute value.

bash

dev browser get attr "@e3" "href"
dev browser get attr "img.logo" "src"

`get count <selector>`#

Count elements matching a CSS selector.

bash

dev browser get count "li.todo-item"
dev browser get count "button"

`get box <selector>`#

Get the bounding box (x, y, width, height) of an element.

bash

dev browser get box "@e5"

`get styles <selector> <properties>`#

Get computed CSS styles. Properties are comma-separated.

bash

dev browser get styles "@e5" "color,font-size,display"

State Queries#

`is visible <selector>`#

Check if an element is visible.

bash

dev browser is visible "@e5"

`is enabled <selector>`#

Check if a form element is enabled (not disabled).

bash

dev browser is enabled "#submit-btn"

`is checked <selector>`#

Check if a checkbox or radio button is checked.

bash

dev browser is checked "@e6"

Console / Errors#

`console list`#

List all console messages (log, info, warn, error).

bash

dev browser console list

`console errors`#

List only console errors.

bash

dev browser console errors

`console clear`#

Clear all captured console messages.

bash

dev browser console clear

`errors list`#

List uncaught JavaScript errors captured via window.onerror and unhandledrejection. Includes source file, line number, and column.

bash

dev browser errors list

Find#

Find elements by accessible properties. Returns matching selectors.

`find role <role>`#

Find elements by ARIA role.

bash

dev browser find role "button"
dev browser find role "textbox"
dev browser find role "link"

`find text <text>`#

Find elements containing specific text.

bash

dev browser find text "Submit"
dev browser find text "Sign In"

`find label <label>`#

Find form elements by their label text.

bash

dev browser find label "Email Address"

`find placeholder <text>`#

Find inputs by placeholder text.

bash

dev browser find placeholder "Search..."

`find testid <id>`#

Find elements by data-testid attribute.

bash

dev browser find testid "login-form"

`find alt <alt>`#

Find elements by alt attribute (images, areas).

bash

dev browser find alt "Company Logo"
dev browser find alt "Hero banner"

`find title <title>`#

Find elements by title attribute.

bash

dev browser find title "Close dialog"
dev browser find title "More options"

`find first <selector>`#

Find the first element matching a CSS selector. Returns a unique selector.

bash

dev browser find first "button.primary"
dev browser find first "li.todo-item"

`find last <selector>`#

Find the last element matching a CSS selector.

bash

dev browser find last "li.todo-item"

`find nth <selector> <index>`#

Find the Nth element matching a CSS selector (0-indexed).

bash

dev browser find nth "li.todo-item" 0   # First item
dev browser find nth "li.todo-item" 2   # Third item

Tab Management#

`list`#

List all open browser tabs with their IDs and URLs.

bash

dev browser list

`open <url>`#

Open a URL in a new browser tab. Returns the new tab's browser ID.

bash

dev browser open "https://example.com"

`open_split <url>`#

Open a URL in a new split browser tab.

bash

dev browser open_split "http://localhost:3000"

`close [browser_id]`#

Close a browser tab. Without an ID, closes the current tab.

bash

dev browser close
dev browser close "abc-123-def"

`focus_tab <browser_id>`#

Switch focus to a specific browser tab.

bash

dev browser focus_tab "abc-123-def"

`tab new <url>`#

Open a URL in a new tab (alias for open).

bash

dev browser tab new "https://example.com"

`tab list`#

List all open tabs (alias for list).

bash

dev browser tab list

`tab switch <browser_id>`#

Switch to a specific tab (alias for focus_tab).

bash

dev browser tab switch "abc-123-def"

`tab close [browser_id]`#

Close a tab (alias for close).

bash

dev browser tab close "abc-123-def"

Dialogs#

Handle JavaScript alert(), confirm(), and prompt() dialogs.

`dialog accept [prompt_text]`#

Accept a pending dialog or pre-configure acceptance for the next one. Optionally provide text for prompt() dialogs.

bash

dev browser dialog accept              # Accept with defaults
dev browser dialog accept "OK"         # Accept prompt with text "OK"

`dialog dismiss`#

Dismiss a pending dialog or pre-configure dismissal for the next one. For confirm() this returns false, for prompt() this returns null.

bash

dev browser dialog dismiss

Usage pattern: Call dialog accept or dialog dismiss before the action that triggers the dialog:

bash

dev browser dialog accept              # Pre-configure
dev browser click "#delete-btn"        # This triggers confirm()
# The dialog is auto-handled

Cookies#

`cookies get [--name <name>] [--domain <domain>]`#

Get cookies, optionally filtered by name and/or domain.

bash

dev browser cookies get                          # All cookies
dev browser cookies get --name session_id        # By name
dev browser cookies get --domain ".example.com"  # By domain

`cookies set <name> <value> [--domain <domain>] [--path <path>]`#

Set a cookie.

bash

dev browser cookies set "theme" "dark"
dev browser cookies set "session" "abc123" --domain ".example.com" --path "/"

`cookies clear [--name <name>] [--domain <domain>]`#

Clear cookies, optionally filtered.

bash

dev browser cookies clear                         # Clear all
dev browser cookies clear --name "session_id"     # Clear specific
dev browser cookies clear --domain ".example.com" # Clear by domain

Storage#

`storage get <local|session> [key]`#

Get localStorage or sessionStorage values. Without a key, returns all entries.

bash

dev browser storage get local                # All localStorage
dev browser storage get local "theme"        # Specific key
dev browser storage get session "cart"       # Session storage key

`storage set <local|session> <key> <value>`#

Set a storage value.

bash

dev browser storage set local "theme" "dark"
dev browser storage set session "step" "3"

`storage clear <local|session> [key]`#

Clear storage. Without a key, clears all entries.

bash

dev browser storage clear local              # Clear all localStorage
dev browser storage clear local "theme"      # Clear specific key
dev browser storage clear session            # Clear all sessionStorage

State Persistence#

`state save <path>`#

Save the browser's current state (cookies, localStorage, sessionStorage, URL) to a JSON file.

bash

dev browser state save /tmp/browser-state.json

`state load <path>`#

Restore browser state from a previously saved JSON file. Restores cookies, navigates to the saved URL, then restores storage.

bash

dev browser state load /tmp/browser-state.json

Frames#

`frame select <selector>`#

Select an iframe. After this, all subsequent commands (click, fill, snapshot, etc.) operate inside the iframe's document.

bash

dev browser frame select "iframe#payment"
dev browser frame select ".embedded-form"

Only works with same-origin iframes. Cross-origin iframes return an error.

`frame main`#

Return to the main document. Call this after you're done interacting with an iframe.

bash

dev browser frame main

Downloads#

`download wait <path> [--timeout <ms>]`#

Wait for a file to appear at the given path. Polls until the file exists and has content.

bash

dev browser download wait "/tmp/report.csv"
dev browser download wait "/tmp/export.zip" --timeout 30000

Script and Style Injection#

`addinitscript <javascript>`#

Add a user script that runs at document start on every page load. Persists across navigations.

bash

dev browser addinitscript "window.__TEST_MODE = true"

`addscript <javascript>`#

Evaluate JavaScript immediately in the page context. Same as eval but named for consistency with the automation API.

bash

dev browser addscript "document.body.style.zoom = '150%'"

`addstyle <css>`#

Inject a CSS stylesheet into the page.

bash

dev browser addstyle "body { background: #1a1a2e; color: #eee; }"
dev browser addstyle ".ad-banner { display: none !important; }"

Agent Presence#

`task <description>`#

Describe the job you are working on. Covers every following action that has no --intent of its own, and marks the tab as agent-driven.

bash

dev browser task "Reproducing the checkout bug"

`done`#

Clear the agent cursor and the URL-bar accent immediately, instead of waiting for the one-minute inactivity timeout.

bash

dev browser done

System#

`ping`#

Health check. Returns {"status":"ok"} if the socket server is running.

bash

dev browser ping

`identify`#

Get information about the running Agentastic instance.

bash

dev browser identify

`capabilities`#

List all capabilities and supported methods.

bash

dev browser capabilities

Examples#

Test a Form Submission#

bash

dev browser navigate "http://localhost:3000/contact"
dev browser wait load
dev browser snapshot

dev browser fill "@e2" "Jane Doe"
dev browser fill "@e3" "jane@example.com"
dev browser fill "@e4" "Hello, this is a test message."
dev browser click "@e5"

dev browser wait text "Thank you"
dev browser get text ".success-message"

Handle a Confirmation Dialog#

bash

# Pre-configure the response before triggering
dev browser dialog accept
dev browser click "#delete-btn"

# Verify the result
dev browser wait text "Item deleted"

Work with Cookies#

bash

# Check existing cookies
dev browser cookies get

# Set a test cookie
dev browser cookies set "test_user" "true" --domain "localhost"

# Reload and verify
dev browser reload
dev browser wait load
dev browser cookies get --name "test_user"

# Clean up
dev browser cookies clear --name "test_user"

Test an Iframe#

bash

dev browser navigate "http://localhost:3000/checkout"
dev browser wait load

# Select the payment iframe
dev browser frame select "iframe#stripe-frame"
dev browser snapshot

# Fill payment details inside the iframe
dev browser fill "@e2" "4242424242424242"
dev browser fill "@e3" "12/28"
dev browser fill "@e4" "123"

# Return to main page
dev browser frame main
dev browser click "#submit-order"

Save and Restore State#

bash

# Login and save state
dev browser navigate "http://localhost:3000/login"
dev browser wait load
dev browser snapshot
dev browser fill "@e2" "admin@example.com"
dev browser fill "@e3" "password"
dev browser click "@e4"
dev browser wait url "/dashboard"
dev browser state save /tmp/logged-in.json

# Later: restore the logged-in state
dev browser state load /tmp/logged-in.json
dev browser wait load
dev browser get title   # Should show Dashboard

Monitor Console Errors#

bash

dev browser navigate "http://localhost:3000"
dev browser wait load
dev browser console errors
dev browser errors list

Multi-Tab Workflow#

bash

# Open two tabs
dev browser open "http://localhost:3000/admin"
dev browser open_split "http://localhost:3000"

# List tabs to get IDs
dev browser list

# Interact with a specific tab
dev browser --browser-id <admin-tab-id> snapshot
dev browser --browser-id <admin-tab-id> click "@e3"

Inject Custom Styles#

bash

# Add dark mode override for testing
dev browser addstyle "body { background: #000 !important; color: #fff !important; }"

# Add a script that runs on every navigation
dev browser addinitscript "console.log('Page loaded:', location.href)"

Verify a UI After Code Changes#

bash

dev browser reload
dev browser wait load
dev browser snapshot
dev browser is visible ".new-feature"
dev browser get text ".new-feature h2"
dev browser console errors

Browser CLI Reference

Overview#

Environment#

Global Flags#

Agent Presence#

Element Selectors#

Commands#

Snapshot and Inspection#

snapshot#

screenshot#

highlight <selector>#

Actions#

click <selector>#

dblclick <selector>#

fill <selector> <value>#

type <selector> <text>#

press <selector> <key>#

keydown <selector> <key>#

keyup <selector> <key>#

hover <selector>#

focus <selector>#

check <selector>#

uncheck <selector>#

select <selector> <value>#

scroll <x> <y> [selector]#

scroll_into_view <selector>#

eval <javascript>#

focus_webview#

is_webview_focused#

Navigation#

navigate <url>#

back#

forward#

reload#

Wait#

wait selector <selector> [--timeout <ms>]#

wait text <text> [--timeout <ms>]#

wait url <pattern> [--timeout <ms>]#

wait load [--timeout <ms>]#

Get#

get url#

get title#

get text [selector]#

get html [selector]#

get value <selector>#

get attr <selector> <attribute>#

get count <selector>#

get box <selector>#

get styles <selector> <properties>#

State Queries#

is visible <selector>#

is enabled <selector>#

is checked <selector>#

Console / Errors#

console list#

console errors#

console clear#

errors list#

Find#

find role <role>#

find text <text>#

find label <label>#

find placeholder <text>#

find testid <id>#

find alt <alt>#

find title <title>#

find first <selector>#

find last <selector>#

find nth <selector> <index>#

Tab Management#

list#

open <url>#

open_split <url>#

close [browser_id]#

focus_tab <browser_id>#

tab new <url>#

tab list#

tab switch <browser_id>#

tab close [browser_id]#

Dialogs#

`snapshot`#

`screenshot`#

`highlight <selector>`#

`click <selector>`#

`dblclick <selector>`#

`fill <selector> <value>`#

`type <selector> <text>`#

`press <selector> <key>`#

`keydown <selector> <key>`#

`keyup <selector> <key>`#

`hover <selector>`#

`focus <selector>`#

`check <selector>`#

`uncheck <selector>`#

`select <selector> <value>`#

`scroll <x> <y> [selector]`#

`scroll_into_view <selector>`#

`eval <javascript>`#

`focus_webview`#

`is_webview_focused`#

`navigate <url>`#

`back`#

`forward`#

`reload`#

`wait selector <selector> [--timeout <ms>]`#

`wait text <text> [--timeout <ms>]`#

`wait url <pattern> [--timeout <ms>]`#

`wait load [--timeout <ms>]`#

`get url`#

`get title`#

`get text [selector]`#

`get html [selector]`#

`get value <selector>`#

`get attr <selector> <attribute>`#

`get count <selector>`#

`get box <selector>`#

`get styles <selector> <properties>`#

`is visible <selector>`#

`is enabled <selector>`#

`is checked <selector>`#

`console list`#

`console errors`#

`console clear`#

`errors list`#

`find role <role>`#

`find text <text>`#

`find label <label>`#

`find placeholder <text>`#

`find testid <id>`#

`find alt <alt>`#

`find title <title>`#

`find first <selector>`#

`find last <selector>`#

`find nth <selector> <index>`#

`list`#

`open <url>`#

`open_split <url>`#

`close [browser_id]`#

`focus_tab <browser_id>`#

`tab new <url>`#

`tab list`#

`tab switch <browser_id>`#

`tab close [browser_id]`#

`dialog accept [prompt_text]`#

`dialog dismiss`#

`cookies get [--name <name>] [--domain <domain>]`#

`cookies set <name> <value> [--domain <domain>] [--path <path>]`#

`cookies clear [--name <name>] [--domain <domain>]`#

`storage get <local|session> [key]`#

`storage set <local|session> <key> <value>`#

`storage clear <local|session> [key]`#

`state save <path>`#

`state load <path>`#

`frame select <selector>`#

`frame main`#

`download wait <path> [--timeout <ms>]`#

`addinitscript <javascript>`#

`addscript <javascript>`#

`addstyle <css>`#

`task <description>`#