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:

dev browser [--browser-id <id>] <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.

Global Flags

Flag	Description
`--browser-id <id>`	Override browser tab ID for this invocation
`--help`	Show help message
`--version`	Show version

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.

dev browser snapshot

Output:

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.

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.

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

Actions

`click <selector>`

Click an element. Scrolls it into view first.

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

`dblclick <selector>`

Double-click an element.

dev browser dblclick "@e3"

`fill <selector> <value>`

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

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.

dev browser type "@e4" "search query"

`press <selector> <key>`

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

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

`keydown <selector> <key>`

Dispatch only a keydown event on an element.

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

`keyup <selector> <key>`

Dispatch only a keyup event on an element.

dev browser keyup "@e4" "Shift"

`hover <selector>`

Hover over an element (fires mouseenter/mouseover).

dev browser hover "@e3"

`focus <selector>`

Focus an element.

dev browser focus "@e4"

`check <selector>`

Check a checkbox.

dev browser check "@e6"

`uncheck <selector>`

Uncheck a checkbox.

dev browser uncheck "@e6"

`select <selector> <value>`

Select an option in a <select> dropdown.

dev browser select "#country" "US"

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

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

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.

dev browser scroll_into_view "@e10"

`eval <javascript>`

Evaluate JavaScript in the page context. Returns the result.

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).

dev browser focus_webview

`is_webview_focused`

Check whether the WKWebView currently has keyboard focus.

dev browser is_webview_focused

Navigation

`navigate <url>`

Navigate to a URL.

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

`back`

Go back in browser history.

dev browser back

`forward`

Go forward in browser history.

dev browser forward

`reload`

Reload the current page.

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.

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.

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.

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').

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

Get

`get url`

Get the current page URL.

dev browser get url

`get title`

Get the current page title.

dev browser get title

`get text [selector]`

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

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.

dev browser get html ".content"

`get value <selector>`

Get the value of a form input.

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

`get attr <selector> <attribute>`

Get an HTML attribute value.

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

`get count <selector>`

Count elements matching a CSS selector.

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.

dev browser get box "@e5"

`get styles <selector> <properties>`

Get computed CSS styles. Properties are comma-separated.

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

State Queries

`is visible <selector>`

Check if an element is visible.

dev browser is visible "@e5"

`is enabled <selector>`

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

dev browser is enabled "#submit-btn"

`is checked <selector>`

Check if a checkbox or radio button is checked.

dev browser is checked "@e6"

Console / Errors

`console list`

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

dev browser console list

`console errors`

List only console errors.

dev browser console errors

`console clear`

Clear all captured console messages.

dev browser console clear

`errors list`

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

dev browser errors list

Find

Find elements by accessible properties. Returns matching selectors.

`find role <role>`

Find elements by ARIA role.

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

`find text <text>`

Find elements containing specific text.

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

`find label <label>`

Find form elements by their label text.

dev browser find label "Email Address"

`find placeholder <text>`

Find inputs by placeholder text.

dev browser find placeholder "Search..."

`find testid <id>`

Find elements by data-testid attribute.

dev browser find testid "login-form"

`find alt <alt>`

Find elements by alt attribute (images, areas).

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

`find title <title>`

Find elements by title attribute.

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.

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

`find last <selector>`

Find the last element matching a CSS selector.

dev browser find last "li.todo-item"

`find nth <selector> <index>`

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

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.

dev browser list

`open <url>`

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

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

`open_split <url>`

Open a URL in a new split browser tab.

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

`close [browser_id]`

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

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

`focus_tab <browser_id>`

Switch focus to a specific browser tab.

dev browser focus_tab "abc-123-def"

`tab new <url>`

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

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

`tab list`

List all open tabs (alias for list).

dev browser tab list

`tab switch <browser_id>`

Switch to a specific tab (alias for focus_tab).

dev browser tab switch "abc-123-def"

`tab close [browser_id]`

Close a tab (alias for close).

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.

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.

dev browser dialog dismiss

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

`addstyle <css>`

Inject a CSS stylesheet into the page.

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

System

`ping`

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

dev browser ping

`identify`

Get information about the running Agentastic instance.

dev browser identify

`capabilities`

List all capabilities and supported methods.

dev browser capabilities

Examples

Test a Form Submission

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

# 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

# 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

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

# 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

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

Multi-Tab Workflow

# 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

# 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

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