import { pageMetadata } from '@/lib/page-metadata';

export const metadata = pageMetadata('commands');

# Commands

## Core

```bash
agent-browser open <url>              # Navigate (aliases: goto, navigate)
agent-browser --risk-mode block open <url>  # Block when verification/captcha interstitial is detected
agent-browser click <sel>             # Click element (--new-tab to open in new tab)
agent-browser dblclick <sel>          # Double-click
agent-browser fill <sel> <text>       # Clear and fill
agent-browser type <sel> <text> [--delay <ms>]  # Type into element
agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
agent-browser keyboard type <text> [--delay <ms>]  # Type at current focus (no selector needed)
agent-browser keyboard inserttext <text>  # Insert text without key events
agent-browser keydown <key>           # Hold key down
agent-browser keyup <key>             # Release key
agent-browser hover <sel>             # Hover element
agent-browser focus <sel>             # Focus element
agent-browser select <sel> <val>      # Select dropdown option
agent-browser check <sel>             # Check checkbox
agent-browser uncheck <sel>           # Uncheck checkbox
agent-browser scroll <dir> [px]       # Scroll (up/down/left/right, --selector <sel>)
agent-browser scrollintoview <sel>    # Scroll element into view
agent-browser drag <src> <dst>        # Drag and drop
agent-browser upload <sel> <files>    # Upload files
agent-browser screenshot [path]       # Screenshot (--full for full page)
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser pdf <path>              # Save page as PDF
agent-browser snapshot                # Accessibility tree with refs
agent-browser eval <js>               # Run JavaScript
agent-browser connect <port|url>      # Connect to browser via CDP
agent-browser --version               # Show CLI version
agent-browser close                   # Close browser (aliases: quit, exit)
```

Fork builds print dual-version metadata with `--version`:

```bash
agent-browser 0.14.0-fork.1 (upstream 0.14.0, fork 1)
```

## Get info

```bash
agent-browser get text <sel>          # Get text content
agent-browser get html <sel>          # Get innerHTML
agent-browser get value <sel>         # Get input value
agent-browser get attr <sel> <attr>   # Get attribute
agent-browser get title               # Get page title
agent-browser get url                 # Get current URL
agent-browser get count <sel>         # Count matching elements
agent-browser get box <sel>           # Get bounding box
agent-browser get styles <sel>        # Get computed styles
```

## Check state

```bash
agent-browser is visible <sel>        # Check if visible
agent-browser is enabled <sel>        # Check if enabled
agent-browser is checked <sel>        # Check if checked
```

## Find elements

Semantic locators with actions (`click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`):

```bash
agent-browser find role <role> <action> [value]
agent-browser find text <text> <action>
agent-browser find label <label> <action> [value]
agent-browser find placeholder <ph> <action> [value]
agent-browser find alt <text> <action>
agent-browser find title <text> <action>
agent-browser find testid <id> <action> [value]
agent-browser find first <sel> <action> [value]
agent-browser find last <sel> <action> [value]
agent-browser find nth <n> <sel> <action> [value]
```

Options:

- `--name <name>` -- filter role by accessible name
- `--exact` -- require exact text match

Examples:

```bash
agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
agent-browser find alt "Logo" click
agent-browser find first ".item" click
agent-browser find last ".item" text
agent-browser find nth 2 ".card" hover
```

## Wait

```bash
agent-browser wait <selector>         # Wait for element
agent-browser wait <ms>               # Wait for time
agent-browser wait 2000-5000          # Random wait between 2-5 seconds
agent-browser wait --text "Welcome"   # Wait for text
agent-browser wait --url "**/dash"    # Wait for URL pattern
agent-browser wait --load networkidle # Wait for load state
agent-browser wait --fn "condition"   # Wait for JS condition
agent-browser wait --download [path]  # Wait for download
```

## Risk Mode

Control how `open`/`navigate` handles verification or captcha interstitials:

```bash
agent-browser --risk-mode warn open https://example.com   # default: wait for auto-clear, then retry/warn with riskSignals
agent-browser --risk-mode block open https://example.com  # fail fast on detection
agent-browser --risk-mode off open https://example.com    # disable detection/retry
```

## Downloads

```bash
agent-browser download <sel> <path>   # Click element to trigger download
agent-browser wait --download [path]  # Wait for any download to complete
```

Use `--download-path <dir>` (or `AGENT_BROWSER_DOWNLOAD_PATH` env) to set a default download directory. Without it, downloads go to a temporary directory that is deleted when the browser closes.

## Tab grouping

```bash
agent-browser open https://example.com
# CDP mode groups tabs when tab-group plugin is installed

# Override the default group title
agent-browser --tab-group "My Agent Group" open https://example.com
```

CDP mode uses a browser extension handshake to group tabs.

- Extension available: tabs are grouped by `session`.
- Extension missing/unavailable: silent no-op (commands still succeed).
- Default titles:
  - `default` session: `Agent Browser Stealth`
  - non-default: `Agent Browser Stealth • <session>`
- Extension side panel (`agent-browser-stealth`) also provides:
  - Session window isolation and deterministic group colors.
  - `Keep Only This`, `Focus`, `Clean Empty Groups` quick actions.
  - Session allowlist editing (domain fallback to `about:blank` when violated).
  - Download routing to `agent-browser-stealth/<session>/...`.
- Use `--tab-group` / `AGENT_BROWSER_TAB_GROUP` for base title.
- Use `AGENT_BROWSER_TAB_GROUP_PLUGIN_ID` (or `--tab-group-plugin-id`) to override expected extension ID.

## Mouse

```bash
agent-browser mouse move <x> <y>      # Move mouse
agent-browser mouse down [button]     # Press button
agent-browser mouse up [button]       # Release button
agent-browser mouse wheel <dy> [dx]   # Scroll wheel
```

## Settings

```bash
agent-browser set viewport <w> <h>    # Set viewport size
agent-browser set device <name>       # Emulate device ("iPhone 14")
agent-browser set geo <lat> <lng>     # Set geolocation
agent-browser set offline [on|off]    # Toggle offline mode
agent-browser set headers <json>      # Extra HTTP headers
agent-browser set credentials <u> <p> # HTTP basic auth
agent-browser set media [dark|light]  # Emulate color scheme (persists for session)
```

Use `--color-scheme` for persistent dark/light mode across all commands:

```bash
agent-browser --color-scheme dark open https://example.com
```

## Cookies & storage

```bash
agent-browser cookies                 # Get all cookies
agent-browser cookies set <name> <val> # Set cookie
agent-browser cookies clear           # Clear cookies

agent-browser storage local           # Get all localStorage
agent-browser storage local <key>     # Get specific key
agent-browser storage local set <k> <v>  # Set value
agent-browser storage local clear     # Clear all

agent-browser storage session         # Same for sessionStorage
```

For `cookies set`, use one of these patterns:

- `--url <url>`
- `--domain <domain> --path <path>`
- omit all three to scope from the current page URL

When `--url` is omitted, `--domain` and `--path` must be provided together.

## Network

```bash
agent-browser network route <url>              # Intercept requests
agent-browser network route <url> --abort      # Block requests
agent-browser network route <url> --body <json>  # Mock response
agent-browser network unroute [url]            # Remove routes
agent-browser network requests                 # View tracked requests
agent-browser network requests --clear         # Clear request log
agent-browser network requests --filter <pat>  # Filter by URL pattern
```

## Tabs & frames

```bash
agent-browser tab                     # List tabs
agent-browser tab new [url]           # New tab
agent-browser tab <n>                 # Switch to tab
agent-browser tab close [n]           # Close tab
agent-browser window new              # Open new browser window
agent-browser frame <sel>             # Switch to iframe
agent-browser frame main              # Back to main frame
```

## Dialogs

```bash
agent-browser dialog accept [text]    # Accept dialog (with optional prompt text)
agent-browser dialog dismiss          # Dismiss dialog
```

## Debug

```bash
agent-browser trace start [path]      # Start trace
agent-browser trace stop [path]       # Stop and save trace
agent-browser profiler start          # Start Chrome DevTools profiling
agent-browser profiler stop [path]    # Stop and save profile (.json)
agent-browser record start <path>     # Start video recording (WebM)
agent-browser record stop             # Stop and save video
agent-browser record restart <path>   # Stop current and start new recording
agent-browser console                 # View console messages
agent-browser console --clear         # Clear console log
agent-browser errors                  # View page errors
agent-browser errors --clear          # Clear error log
agent-browser highlight <sel>         # Highlight element
```

## State management

```bash
agent-browser state save <path>       # Save auth state to file
agent-browser state load <path>       # Load auth state from file
agent-browser state list              # List saved state files
agent-browser state show <file>       # Show state summary
agent-browser state rename <old> <new> # Rename state file
agent-browser state clear [name]      # Clear states for session name
agent-browser state clear --all       # Clear all saved states
agent-browser state clean --older-than <days>  # Delete old states
```

## Sessions

```bash
agent-browser session                 # Show current session name
agent-browser session list            # List active sessions
```

## Navigation

```bash
agent-browser back                    # Go back
agent-browser forward                 # Go forward
agent-browser reload                  # Reload page
```

## Global options

```bash
--session <name>         # Isolated browser session
--session-name <name>    # Auto-save/restore session state (defaults to --session when omitted)
--state <path>           # Load storage state from JSON file
--headers <json>         # HTTP headers scoped to URL's origin
--executable-path <path> # Custom browser executable
--extension <path>       # Load browser extension (repeatable)
--args <args>            # Browser launch args (comma separated)
--user-agent <ua>        # Custom User-Agent string
--proxy <url>            # Proxy server URL
--proxy-bypass <hosts>   # Hosts to bypass proxy
--ignore-https-errors    # Ignore HTTPS certificate errors
--allow-file-access      # Allow file:// URLs to access local files (Chromium only)
--stealth                # Stealth mode (always on by default)
-p, --provider <name>    # Browser provider (ios, browserbase, kernel, browseruse)
--device <name>          # iOS device name (e.g., "iPhone 15 Pro")
--json                   # JSON output (for scripts)
--full, -f               # Full page screenshot
--annotate               # Annotated screenshot with numbered element labels
--headed                 # Show browser window (not headless)
--cdp <port|url>         # Connect via Chrome DevTools Protocol (port or WebSocket URL)
--auto-connect           # Auto-discover and connect to running Chrome
--tab-group <name>       # Base title for agent tab groups (CDP plugin mode)
--tab-group-plugin-id <id> # Expected extension ID for tab-group handshake
--debug                  # Debug output (includes stealth connection type + capabilities)
```

## Command chaining

Chain commands with `&&` in a single shell invocation. The browser persists via a background daemon, so chaining works naturally and is more efficient than separate calls:

```bash
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
```

Use `&&` when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact with those refs).

## Local files

Open local files (PDFs, HTML) using `file://` URLs:

```bash
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png
```

The `--allow-file-access` flag enables JavaScript to access other local files. Chromium only.