> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# dev browser CLI reference

> Complete reference for the dev browser command. Control Agentastic's built-in browser from the terminal to automate navigation, interactions, and inspection.

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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
dev browser highlight "@e5"
dev browser highlight "#main-content"
```

### Actions

#### `click <selector>`

Click an element. Scrolls it into view first.

```bash theme={null}
dev browser click "@e5"
dev browser click "#submit-btn"
```

#### `dblclick <selector>`

Double-click an element.

```bash theme={null}
dev browser dblclick "@e3"
```

#### `fill <selector> <value>`

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

```bash theme={null}
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.

```bash theme={null}
dev browser type "@e4" "search query"
```

#### `press <selector> <key>`

Press a key on an element. Dispatches `keydown`, `keypress`, and `keyup`. Supports modifier keys.

```bash theme={null}
dev browser press "@e4" "Enter"
dev browser press "@e4" "Tab"
```

#### `keydown <selector> <key>`

Dispatch only a `keydown` event on an element.

```bash theme={null}
dev browser keydown "@e4" "Shift"
dev browser keydown "@e4" "ArrowDown"
```

#### `keyup <selector> <key>`

Dispatch only a `keyup` event on an element.

```bash theme={null}
dev browser keyup "@e4" "Shift"
```

#### `hover <selector>`

Hover over an element. Fires `mouseenter` and `mouseover`.

```bash theme={null}
dev browser hover "@e3"
```

#### `focus <selector>`

Focus an element.

```bash theme={null}
dev browser focus "@e4"
```

#### `check <selector>`

Check a checkbox.

```bash theme={null}
dev browser check "@e6"
```

#### `uncheck <selector>`

Uncheck a checkbox.

```bash theme={null}
dev browser uncheck "@e6"
```

#### `select <selector> <value>`

Select an option in a `<select>` dropdown.

```bash theme={null}
dev browser select "#country" "US"
```

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

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

```bash theme={null}
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 theme={null}
dev browser scroll_into_view "@e10"
```

#### `eval <javascript>`

Evaluate JavaScript in the page context. Returns the result.

```bash theme={null}
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.

```bash theme={null}
dev browser focus_webview
```

#### `is_webview_focused`

Check whether the WKWebView currently has keyboard focus.

```bash theme={null}
dev browser is_webview_focused
```

### Navigation

#### `navigate <url>`

Navigate to a URL.

```bash theme={null}
dev browser navigate "https://example.com"
dev browser navigate "http://localhost:3000/dashboard"
```

#### `back`

Go back in browser history.

```bash theme={null}
dev browser back
```

#### `forward`

Go forward in browser history.

```bash theme={null}
dev browser forward
```

#### `reload`

Reload the current page.

```bash theme={null}
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.

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
dev browser wait load
dev browser wait load --timeout 15000
```

### Get

#### `get url`

Get the current page URL.

```bash theme={null}
dev browser get url
```

#### `get title`

Get the current page title.

```bash theme={null}
dev browser get title
```

#### `get text [selector]`

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

```bash theme={null}
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 theme={null}
dev browser get html ".content"
```

#### `get value <selector>`

Get the value of a form input.

```bash theme={null}
dev browser get value "input[name=email]"
dev browser get value "@e4"
```

#### `get attr <selector> <attribute>`

Get an HTML attribute value.

```bash theme={null}
dev browser get attr "@e3" "href"
dev browser get attr "img.logo" "src"
```

#### `get count <selector>`

Count elements matching a CSS selector.

```bash theme={null}
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 theme={null}
dev browser get box "@e5"
```

#### `get styles <selector> <properties>`

Get computed CSS styles. Properties are comma-separated.

```bash theme={null}
dev browser get styles "@e5" "color,font-size,display"
```

### State queries

#### `is visible <selector>`

Check if an element is visible.

```bash theme={null}
dev browser is visible "@e5"
```

#### `is enabled <selector>`

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

```bash theme={null}
dev browser is enabled "#submit-btn"
```

#### `is checked <selector>`

Check if a checkbox or radio button is checked.

```bash theme={null}
dev browser is checked "@e6"
```

### Console and errors

#### `console list`

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

```bash theme={null}
dev browser console list
```

#### `console errors`

List only console errors.

```bash theme={null}
dev browser console errors
```

#### `console clear`

Clear all captured console messages.

```bash theme={null}
dev browser console clear
```

#### `errors list`

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

```bash theme={null}
dev browser errors list
```

### Find

Find commands locate elements by accessible properties and return matching selectors.

#### `find role <role>`

Find elements by ARIA role.

```bash theme={null}
dev browser find role "button"
dev browser find role "textbox"
dev browser find role "link"
```

#### `find text <text>`

Find elements containing specific text.

```bash theme={null}
dev browser find text "Submit"
dev browser find text "Sign In"
```

#### `find label <label>`

Find form elements by their label text.

```bash theme={null}
dev browser find label "Email Address"
```

#### `find placeholder <text>`

Find inputs by placeholder text.

```bash theme={null}
dev browser find placeholder "Search..."
```

#### `find testid <id>`

Find elements by `data-testid` attribute.

```bash theme={null}
dev browser find testid "login-form"
```

#### `find alt <alt>`

Find elements by `alt` attribute (images and areas).

```bash theme={null}
dev browser find alt "Company Logo"
dev browser find alt "Hero banner"
```

#### `find title <title>`

Find elements by `title` attribute.

```bash theme={null}
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 theme={null}
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 theme={null}
dev browser find last "li.todo-item"
```

#### `find nth <selector> <index>`

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

```bash theme={null}
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 theme={null}
dev browser list
```

#### `open <url>`

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

```bash theme={null}
dev browser open "https://example.com"
```

#### `open_split <url>`

Open a URL in a new split browser tab.

```bash theme={null}
dev browser open_split "http://localhost:3000"
```

#### `close [browser_id]`

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

```bash theme={null}
dev browser close
dev browser close "abc-123-def"
```

#### `focus_tab <browser_id>`

Switch focus to a specific browser tab.

```bash theme={null}
dev browser focus_tab "abc-123-def"
```

#### `tab new <url>`

Open a URL in a new tab. Alias for `open`.

```bash theme={null}
dev browser tab new "https://example.com"
```

#### `tab list`

List all open tabs. Alias for `list`.

```bash theme={null}
dev browser tab list
```

#### `tab switch <browser_id>`

Switch to a specific tab. Alias for `focus_tab`.

```bash theme={null}
dev browser tab switch "abc-123-def"
```

#### `tab close [browser_id]`

Close a tab. Alias for `close`.

```bash theme={null}
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.

```bash theme={null}
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 theme={null}
dev browser dialog dismiss
```

<Tip>
  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.
</Tip>

### Cookies

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

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

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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.

```bash theme={null}
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 theme={null}
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.

```bash theme={null}
dev browser frame select "iframe#payment"
dev browser frame select ".embedded-form"
```

<Note>
  Frame selection only works with same-origin iframes. Cross-origin iframes return an error.
</Note>

#### `frame main`

Return to the main document. Call this after you finish interacting with an iframe.

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
dev browser addscript "document.body.style.zoom = '150%'"
```

#### `addstyle <css>`

Inject a CSS stylesheet into the page.

```bash theme={null}
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.

```bash theme={null}
dev browser ping
```

#### `identify`

Get information about the running Agentastic instance.

```bash theme={null}
dev browser identify
```

#### `capabilities`

List all capabilities and supported methods.

```bash theme={null}
dev browser capabilities
```

## Examples

### Test a form submission

```bash theme={null}
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 theme={null}
# 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 theme={null}
# 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 theme={null}
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 theme={null}
# 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 theme={null}
dev browser navigate "http://localhost:3000"
dev browser wait load
dev browser console errors
dev browser errors list
```

### Multi-tab workflow

```bash theme={null}
# 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 theme={null}
# 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 theme={null}
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
```