Docyrus Browser CLI

Browser automation via a persistent daemon that holds a raw CDP (Chrome DevTools Protocol) WebSocket connection. No Puppeteer/Playwright framework — direct CDP for speed and flexibility.

Works in both local mode (Chrome on :9222) and remote sandbox mode (Cloudflare Browser Rendering).

Architecture

docyrus browser <command>
  → tool script (Node.js)
    → HTTP request to daemon (localhost:9333)
      → raw CDP WebSocket to Chrome/Cloudflare

The daemon starts automatically on the first command and stays alive for 5 minutes of idle time. All commands share the same browser connection — no reconnection overhead.

Core Workflow for Self-Testing

# 1. Start browser + daemon
docyrus browser start

# 2. Navigate to preview
docyrus browser nav https://preview-url.example.com

# 3. Wait for page to fully load
docyrus browser wait --idle

# 4. Discover interactive elements
docyrus browser snapshot

# 5. Interact using refs from snapshot
docyrus browser fill @e2 "user@example.com"
docyrus browser click @e3

# 6. Verify results
docyrus browser wait --selector ".success-message"
docyrus browser screenshot
docyrus browser console --level error
docyrus browser network --method POST --status 2xx

Commands

Session Management

docyrus browser start                     # Start Chrome + daemon
docyrus browser start --profile           # Start with user's Chrome profile (local only)
docyrus browser close                     # Stop daemon and disconnect

Navigation

docyrus browser nav <url>                 # Navigate active tab
docyrus browser nav <url> --new           # Open in new tab
docyrus browser nav <url> --reload        # Navigate and force reload

Waiting

docyrus browser wait --idle               # Wait for network idle
docyrus browser wait --selector "h1"      # Wait for element to appear
docyrus browser wait --url "**/dashboard" # Wait for URL to match pattern
docyrus browser wait 2000                 # Wait fixed milliseconds
docyrus browser wait --idle --timeout 30000

Page Snapshot (Element Discovery)

docyrus browser snapshot                  # Interactive elements with refs (@e1, @e2, ...)
docyrus browser snapshot --all            # Include non-interactive elements
docyrus browser snapshot --selector "#app" # Scope to a subtree

Returns:

{
  "snapshot": [
    { "ref": "@e1", "tag": "input", "type": "email", "placeholder": "Email" },
    { "ref": "@e2", "tag": "input", "type": "password" },
    { "ref": "@e3", "tag": "button", "text": "Sign In" }
  ]
}

Element Interaction

Three targeting modes — refs, CSS selectors, or x,y coordinates:

docyrus browser click @e3                 # Click by snapshot ref
docyrus browser click "button.submit"     # Click by CSS selector
docyrus browser click 350 200             # Coordinate click (compositor-level)
docyrus browser fill @e1 "user@test.com"  # Clear + type into input
docyrus browser select @e4 "Option A"    # Select dropdown option

Coordinate clicks pass through iframes, shadow DOM, and cross-origin frames at the compositor level — no DOM piercing needed. Use info for viewport dimensions.

JavaScript Evaluation

docyrus browser eval 'document.title'
docyrus browser eval 'const rows = document.querySelectorAll("tr"); return rows.length'
docyrus browser eval 'await fetch("/api/health").then(r => r.json())'

Supports expressions and multi-statement code. Uses CDP Runtime.evaluate with awaitPromise: true.

Screenshots

docyrus browser screenshot               # Viewport screenshot → /tmp
docyrus browser screenshot --full         # Full page
docyrus browser screenshot --base64       # Base64 in JSON (for remote/sandbox mode)

Console Messages

docyrus browser console                   # Captured logs (last 50)
docyrus browser console --level error     # Only errors
docyrus browser console --listen 5000     # Listen for 5 seconds via CDP events

Run console once early to install the interceptor.

Network Inspection

docyrus browser network                   # All captured requests
docyrus browser network --method POST     # Only POST requests
docyrus browser network --status 4xx      # Only 4xx responses
docyrus browser network --url "/api/"     # URL substring filter
docyrus browser network --listen 5000     # Listen for 5 seconds

Network events are captured automatically by the daemon (CDP Network.enable).

Docyrus Devtools

Read runtime diagnostics from @docyrus/devtools (must be loaded on the page):

docyrus browser devtools state              # Full devtools state
docyrus browser devtools errors             # Collected API errors
docyrus browser devtools issues             # Detected API usage issues (e.g. missing fields, bad queries)
docyrus browser devtools console            # Console entries captured by devtools
docyrus browser devtools console --level error  # Filtered by level

Use after interacting with a Docyrus-backed app to catch API misuse, failed requests, and runtime issues that console --level error alone would miss.

Content Extraction

docyrus browser content <url>             # Extract readable markdown from URL

Cookies

docyrus browser cookies                   # All cookies (via CDP Network.getCookies)
docyrus browser cookies --name "session"
docyrus browser cookies --domain ".app.com"

Page Info

docyrus browser info                      # URL, title, viewport, scroll, page dimensions

Tab Management

docyrus browser tabs                      # List all tabs
docyrus browser tabs --switch 1           # Switch to tab by index

CDP Scripts

docyrus browser run-script script.js

The script receives raw CDP helpers: cdp, evaluate, navigate, captureScreenshot, clickAt, typeText, pressKey, pageInfo, drainEvents, waitForCondition.

Tips for AI Agents

1. start auto-launches the daemon — subsequent commands are fast (no reconnection)
2. Always wait --idle after nav before taking snapshots or screenshots
3. Use snapshot → refs → click/fill for reliable element targeting
4. Re-snapshot after interactions to get fresh refs
5. Use coordinate click 350 200 for elements inside iframes or shadow DOM
6. Check console --level error and network --status 5xx to catch runtime issues
7. Use screenshot --base64 in remote/sandbox mode
8. close stops the daemon; it auto-stops after 5 minutes idle anyway