Gsd Browser

gsd-browser navigate https://example.com/form
gsd-browser snapshot
# Output: @v1:e1 [input type="email"], @v1:e2 [input type="password"], @v1:e3 [button] "Submit"

gsd-browser fill-ref @v1:e1 "user@example.com"
gsd-browser fill-ref @v1:e2 "password123"
gsd-browser click-ref @v1:e3
gsd-browser wait-for --condition network_idle
gsd-browser snapshot  # REQUIRED — old refs are now stale

# Chain navigate + wait + snapshot
gsd-browser navigate https://example.com && gsd-browser wait-for --condition network_idle && gsd-browser snapshot

# Chain multiple interactions
gsd-browser fill-ref @v1:e1 "user@example.com" && gsd-browser fill-ref @v1:e2 "password123" && gsd-browser click-ref @v1:e3

gsd-browser navigate <url>                        # Navigate to a URL
gsd-browser back                                   # Go back in browser history
gsd-browser forward                                # Go forward in browser history
gsd-browser reload                                 # Reload the current page

# Click
gsd-browser click <selector>                       # Click by CSS selector
gsd-browser click --x 100 --y 200                  # Click by coordinates (no selector)

# Type — positional: <selector> <text>
gsd-browser type <selector> <text>                 # Atomic fill (replaces content)
gsd-browser type <selector> <text> --slowly        # Character-by-character
gsd-browser type <selector> <text> --clear-first   # Clear field before typing
gsd-browser type <selector> <text> --submit        # Press Enter after typing

# Other interaction — all positional selectors
gsd-browser press <key>                            # Press key: Enter, Escape, Tab, Meta+A
gsd-browser hover <selector>                       # Hover over element
gsd-browser scroll --direction down                # Scroll down 300px (default)
gsd-browser scroll --direction up --amount 500     # Scroll up 500px
gsd-browser select-option <selector> <option>      # Select dropdown by label or value
gsd-browser set-checked <selector> --checked       # Check checkbox/radio (omit --checked to uncheck)
gsd-browser drag <source-selector> <target-selector>  # Drag-and-drop
gsd-browser upload-file <selector> <file>...       # Set files on <input type="file">
gsd-browser set-viewport --preset mobile           # Preset: mobile, tablet, desktop, wide
gsd-browser set-viewport --width 1920 --height 1080  # Custom dimensions

# Take snapshot
gsd-browser snapshot                               # Snapshot interactive elements, assign refs
gsd-browser snapshot --selector "form"             # Scope to a CSS selector
gsd-browser snapshot --mode <mode>                 # Semantic mode (see below)
gsd-browser snapshot --limit 80                    # Increase element limit (default: 40)

# Use refs — all positional
gsd-browser get-ref <ref>                          # Get metadata for a ref
gsd-browser click-ref <ref>                        # Click element by ref
gsd-browser hover-ref <ref>                        # Hover element by ref
gsd-browser fill-ref <ref> <text>                  # Type into element by ref

gsd-browser accessibility-tree                     # Full accessibility tree (roles, names, states)
gsd-browser find --text "Sign In"                  # Find elements by text (case-insensitive)
gsd-browser find --role button                     # Find by ARIA role
gsd-browser find --selector ".my-class"            # Find by CSS selector
gsd-browser find --role link --limit 50            # Increase limit (default: 20)
gsd-browser page-source                            # Get raw HTML of page
gsd-browser page-source --selector "main"          # Scoped HTML source
gsd-browser eval '<js-expression>'                 # Evaluate JavaScript in page context

gsd-browser assert --checks '[
  {"kind": "url_contains", "text": "/dashboard"},
  {"kind": "text_visible", "text": "Welcome"},
  {"kind": "selector_visible", "selector": "#user-menu"},
  {"kind": "value_equals", "selector": "input[name=email]", "value": "user@test.com"},
  {"kind": "no_console_errors"},
  {"kind": "no_failed_requests"}
]'

gsd-browser batch --steps '[
  {"action": "navigate", "url": "https://example.com"},
  {"action": "wait_for", "condition": "network_idle"},
  {"action": "click", "selector": "#login-btn"},
  {"action": "type", "selector": "input[name=email]", "text": "user@test.com"},
  {"action": "type", "selector": "input[name=password]", "text": "secret", "submit": true},
  {"action": "assert", "checks": [{"kind": "url_contains", "text": "/dashboard"}]}
]'

# With --summary-only to reduce output
gsd-browser batch --steps '[...]' --summary-only

gsd-browser wait-for --condition selector_visible --value "#content"
gsd-browser wait-for --condition selector_hidden --value ".spinner"
gsd-browser wait-for --condition url_contains --value "/dashboard"
gsd-browser wait-for --condition network_idle
gsd-browser wait-for --condition delay --value 2000
gsd-browser wait-for --condition text_visible --value "Success"
gsd-browser wait-for --condition text_hidden --value "Loading"
gsd-browser wait-for --condition request_completed --value "/api/data"
gsd-browser wait-for --condition console_message --value "ready"
gsd-browser wait-for --condition element_count --value ".item" --threshold ">=5"
gsd-browser wait-for --condition region_stable --value "#content"

# Custom timeout (default: 10000ms)
gsd-browser wait-for --condition selector_visible --value "#slow" --timeout 30000

# Analyze form structure
gsd-browser analyze-form
gsd-browser analyze-form --selector "#signup-form"

# Fill by field identifiers (resolved: label -> name -> placeholder -> aria-label)
gsd-browser fill-form --values '{"Email": "a@b.com", "Password": "secret", "Country": "US"}'
gsd-browser fill-form --values '{"Email": "a@b.com"}' --submit  # Fill and click submit
gsd-browser fill-form --values '{"Email": "a@b.com"}' --selector "#login-form"

# Find top candidates for an intent (returns scored matches with selectors)
gsd-browser find-best --intent submit_form
gsd-browser find-best --intent accept_cookies
gsd-browser find-best --intent primary_cta --scope "#modal"

# Act: find best match and click/focus it in one call
gsd-browser act --intent submit_form
gsd-browser act --intent accept_cookies
gsd-browser act --intent fill_email

gsd-browser list-pages                             # List all open tabs
gsd-browser switch-page <id>                       # Switch to tab by ID (positional)
gsd-browser close-page <id>                        # Close a tab by ID (positional)

gsd-browser list-frames                            # List all frames (main + iframes)
gsd-browser select-frame --name "iframe-name"      # Select frame by name
gsd-browser select-frame --url-pattern "embed"     # Select frame by URL substring
gsd-browser select-frame --index 0                 # Select by index
gsd-browser select-frame --name main               # Return to main frame

gsd-browser console                                # Get console log entries (clears buffer)
gsd-browser console --no-clear                     # Read without clearing
gsd-browser network                                # Get network log entries
gsd-browser dialog                                 # Get dialog events (alert, confirm, prompt)
gsd-browser timeline                               # Query the action timeline
gsd-browser session-summary                        # Diagnostic summary of current session
gsd-browser debug-bundle                           # Full debug bundle: screenshot + logs + timeline + a11y tree

gsd-browser view                                   # Open the live viewer
gsd-browser view --print-only                      # Print tokenized URL only
gsd-browser view --interactive                     # Interactive local workbench
gsd-browser view --history                         # Open history-focused viewer
gsd-browser view --history --print-only            # Print history URL only

gsd-browser goal "Find the checkout button"        # Set viewer goal banner
gsd-browser goal --clear                           # Clear goal banner

gsd-browser control-state                          # Show shared owner/mode/version
gsd-browser takeover                               # Give page input to the viewer
gsd-browser release-control                        # Return page input to the agent
gsd-browser pause                                  # Pause before next narrated action
gsd-browser resume                                 # Resume actions
gsd-browser step                                   # Allow one action, then pause
gsd-browser abort                                  # Abort next gated action
gsd-browser sensitive-on                           # Local human control with redaction
gsd-browser sensitive-off                          # Leave sensitive mode

gsd-browser --session demo navigate https://example.com
gsd-browser --session demo view --print-only
gsd-browser --session demo click "h1"

gsd-browser annotations
gsd-browser annotation-get <id>
gsd-browser annotation-clear <id>
gsd-browser annotation-clear --all
gsd-browser annotation-resolve <id>
gsd-browser annotation-export --output annotations.json
gsd-browser annotation-request "Select the button to restyle"

gsd-browser record-start --name checkout-bug
gsd-browser record-stop
gsd-browser record-pause
gsd-browser record-resume
gsd-browser recordings
gsd-browser recording-get <id>
gsd-browser recording-export <id> --output <path>
gsd-browser recording-discard <id>
gsd-browser recording-validate <id-or-path> --json

gsd-browser --session demo --no-narration-delay click "h1"