Browser Automation with airbrow
Quick start
open # Start browser
goto https://example.com # Navigate to page
observe # Get interactive elements with refs
click r1 # Click element by ref
fill r2 "text" # Fill input by ref
quit # Close browser
Core workflow
- Start:
open (or open -v for visible browser)
- Navigate:
goto <url>
- Observe:
observe (returns elements with refs like r1, r2)
- Interact using refs from observe output
- Re-observe after navigation or significant DOM changes
Commands
Session
open # Start headless browser
open -v # Start visible browser (headed)
reconnect # Reconnect to browser if disconnected
quit # Close browser and exit
Navigation
goto <url> # Navigate to URL
back # Go back
forward # Go forward
reload # Reload page
Observation (page analysis)
observe # Interactive elements in viewport (recommended)
snap # URL and title only
snapshot # Full page with text content
content # Main HTML content (5KB max)
content full # Full HTML
Interactions (use refs from observe)
click r1 # Click element
dblclick r1 # Double-click
fill r2 "text" # Clear and fill input
type r2 "text" # Type char-by-char (for autocomplete)
press Enter # Press key
press Tab # Tab key
press Escape # Escape key
hover r1 # Hover element
focus r1 # Focus element
blur # Remove focus
check r1 # Check checkbox
uncheck r1 # Uncheck checkbox
select r1 "value" # Select dropdown option
drag r1 r2 # Drag from r1 to r2
Scroll
scroll down # Scroll down 500px
scroll up # Scroll up 500px
scroll 1000 # Scroll down 1000px
scroll -500 # Scroll up 500px
scrollto r1 # Scroll element into view
top # Scroll to top
bottom # Scroll to bottom
pageup # Scroll up by viewport
pagedown # Scroll down by viewport
Get information
get text r1 # Get element text
get value r1 # Get input value
get html r1 # Get element HTML
get title # Get page title
get url # Get current URL
get count "selector" # Count matching elements
Screenshots & PDF
screenshot # Save to shot.png
screenshot path.png # Save to specific path
pdf # Save to page.pdf
pdf output.pdf # Save to specific path
Wait
wait 2000 # Wait milliseconds
wait r1 # Wait for element
wait r1 5000 # Wait for element with timeout
waitvisible r1 # Wait for element to be visible
waitresponse api/data # Wait for network response matching pattern
isvisible r1 # Check if element is visible
ischecked r1 # Check if checkbox is checked
Multi-tab
newtab # Open new blank tab
newtab https://... # Open new tab with URL
tabs # List all tabs
tab 0 # Switch to tab 0
tab 1 # Switch to tab 1
closetab # Close current tab
closetab 2 # Close tab 2
Iframe
frames # List all frames
frame 0 # Switch to frame by index
frame "name" # Switch to frame by name
mainframe # Return to main frame
Network control
block "*.jpg" # Block URLs matching pattern
block "ads.com/*" # Block ad domain
blockimages # Block all images
blockmedia # Block video/audio
blockfonts # Block fonts
unblock # Remove all blocks
Cookies
cookies # Get all cookies
cookies .example.com # Get cookies for domain
setcookie name val .example.com # Set cookie
delcookie name .example.com # Delete cookie
clearcookies # Clear all cookies
Storage
storage get key # Get localStorage value
storage set key value # Set localStorage value
storage del key # Delete key
storage clear # Clear localStorage
Files
upload r1 /path/file.pdf # Upload file to input
upload r1 file1.pdf file2.pdf # Upload multiple files
downloadpath /path/to/downloads # Set download directory
Device emulation
viewport 1920 1080 # Set viewport size
mobile # Mobile emulation (375x667)
dark # Enable dark mode
light # Enable light mode
print # Print media type
JavaScript
eval "document.title" # Execute JavaScript
eval "window.scrollY" # Get scroll position
eval "localStorage.clear()" # Clear storage via JS
Semantic locators (alternative to refs)
click text:Submit # Click by text content
click role:button # Click by ARIA role
fill label:Email "user@test.com" # Fill by label
fill placeholder:Search "query" # Fill by placeholder
click //button[@type='submit'] # Click by XPath
Example: Google search
open
goto https://google.com
observe
# Output: [["r1","in","Search"],["r2","btn","Google Search"]]
fill r1 "claude ai"
press Enter
wait 1000
observe
Example: Form submission
open
goto https://example.com/login
observe
# Output: [["r1","in","Email"],["r2","in","Password"],["r3","btn","Sign In"]]
fill r1 "user@example.com"
fill r2 "password123"
click r3
wait 2000
observe
Example: Multi-tab research
open
goto https://google.com
observe
newtab https://bing.com
observe
tabs
# Output: {"tabs":[{"i":0,"u":"google.com"},{"i":1,"u":"bing.com"}]}
tab 0
observe
Example: Scraping with network optimization
open
blockimages
blockmedia
goto https://news.ycombinator.com
observe
content
Example: Dark mode screenshot
open
goto https://example.com
dark
wait 500
screenshot dark_mode.png
Example: File upload
open
goto https://example.com/upload
observe
# Find file input: [["r3","in","Choose File"]]
upload r3 /path/to/document.pdf
click text:Submit
waitresponse upload 30000
observe
Output format
observe output
{"e":[["r1","btn","Submit"],["r2","in","Email"]],"n":2,"t":"Page Title","u":"https://example.com"}
e: Elements array [ref, role, label]n: Element countt: Page titleu: Current URL
Element roles
| Role |
Meaning |
a |
Link |
btn |
Button |
in |
Input |
sel |
Select |
txt |
Textarea |
combobox |
Combobox |
Performance
| Metric |
airbrow |
Playwright |
| Memory |
3.5 MB |
150+ MB |
| Context |
~2 KB |
~20 KB |
| Startup |
~200ms |
~1500ms |
| Binary |
2 MB |
Node runtime |
Tips
- Always
observe before interacting to get current refs
- Use
blockimages for faster page loads
- Use
type instead of fill for search boxes (triggers autocomplete)
- Refs (
r1, r2) are more reliable than CSS selectors
observe only returns elements visible in viewport - use pagedown to see more- Re-observe after any navigation or DOM change
diegosouzapw