dev browser CLI reference

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, giving agents full programmatic access to browser state and interactions during development and testing. All commands follow this pattern:

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

Environment variables

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 the browser tab ID for this invocation
`--help`	Show help message
`--version`	Show version

Element selectors

Commands that accept a <selector> argument support two formats:

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

Use @eN references when you want to refer to an element returned by a previous snapshot call. Use CSS selectors for elements you can identify directly.

Commands

Snapshot and inspection

`snapshot`

Take an accessibility snapshot of the page. Returns a tree of elements with roles, names, and @eN references you can use in subsequent commands.

dev browser snapshot

Example 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 a 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, and keyup for each character. Use this when fill does not trigger the right events.

dev browser type "@e4" "search query"

`press <selector> <key>`

Press a key on an element. Dispatches keydown, keypress, and 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 and 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 scroll 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, giving 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

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

`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 and 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 commands locate elements by accessible properties and return 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 and 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

These commands 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

Call dialog accept or dialog dismiss before the action that triggers the dialog. Agentastic pre-configures the response and handles the dialog automatically when it appears.

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, and 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, and so on) operate inside the iframe’s document.

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

Frame selection only works with same-origin iframes. Cross-origin iframes return an error.

`frame main`

Return to the main document. Call this after you finish 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

Get Started

Features

Guides

Reference

Help

Documentation Index

​Environment variables

​Global flags

​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 and 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

Environment variables

Global flags

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 and 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

`dialog accept [prompt_text]`

`dialog dismiss`

Cookies