Guides

CLI Reference

The mr-browser binary provides four subcommands. Install it with make install or build with make build (produces bin/mr-browser).

# Global flags

mr-browser --help

bash

mr-browser [flags] <command>

Global flags (available on every command):
  --headless          Run browser headlessly (default: true)
  --headless=false    Show the browser window
  --chromium <path>   Path to Chromium executable (auto-detected by default)
  --no-sandbox        Disable Chromium sandbox (required inside Docker)
  --db <path>         Path to SQLite fingerprint database (default: ./mrbrowser.db)
  --log-level <lvl>   Log verbosity: debug, info, warn, error (default: info)
  --config <file>     Config file path (default: $HOME/.mrbrowser.yaml or ./.mrbrowser.yaml)

Environment variables (MRBROWSER_ prefix):
  MRBROWSER_HEADLESS=true
  MRBROWSER_NO_SANDBOX=true
  MRBROWSER_CHROMIUM_PATH=/usr/bin/chromium
  MRBROWSER_DB_PATH=/app/data/mrbrowser.db
  MRBROWSER_LOG_LEVEL=info

# run

Execute a YAML workflow from start to finish. Exits with code 0 on success, 1 on failure.

mr-browser run

bash

# Run a YAML workflow headlessly (default)
mr-browser run login.yaml

# Show the browser window
mr-browser run login.yaml --headless=false

# Use a custom database path
mr-browser run login.yaml --db ./ci/memory.db

# Verbose logging
mr-browser run login.yaml --log-level debug

# Output:
#   Task: login_admin
#   Steps: 3/3 passed
#   Duration: 2.4s
#   Status: SUCCESS

# debug

Step through a workflow interactively — pause after each step, inspect the result, and decide to continue, skip, or abort. Perfect for writing new flows.

mr-browser debug

bash

# Step through a workflow interactively
mr-browser debug login.yaml --headless=false

# At each step you are prompted:
#   ── Step 1/3 [open] ─────────────────
#     URL: https://corp-portal.internal/login
#   Press ENTER to execute, 's' to skip, 'q' to quit: 

# Keyboard shortcuts during debug:
#   ENTER  — execute the current step
#   s      — skip the current step
#   q      — quit the debug session

Tip

Always use --headless=false with debug so you can visually watch what the engine is doing at each step.

# screenshot

Navigate to a URL and capture a full-page PNG screenshot. Useful as a quick sanity check or for visual regression baselines.

mr-browser screenshot

bash

# Capture a screenshot of a URL
mr-browser screenshot https://example.com

# Save to a specific file
mr-browser screenshot https://example.com --output page.png
mr-browser screenshot https://example.com -o reports/snapshot.png

# With headed browser (useful for pages that need interaction first)
mr-browser screenshot https://app.example.com --headless=false

# inspect

Navigate to a URL and print all elements the engine can see. Use this to explore a new page and craft accurate intent strings for your workflows. --target lets you test a specific intent string and see which element it resolves to and with what confidence.

mr-browser inspect

bash

# List all interactive elements on a page
mr-browser inspect https://example.com

# Show only visible elements
mr-browser inspect https://example.com --visible-only

# Resolve a specific intent and show ranked candidates
mr-browser inspect https://example.com --target "login button"

# Output as JSON (useful for piping to jq)
mr-browser inspect https://example.com --json | jq '.[0]'

# Example output:
#   🌐 https://example.com
#   📄 Example Domain
#   Found 12 elements
#
#   ── INPUTS ─────────────────────
#   👁  <email>      text      Email address [clickable]
#   👁  <password>   password  Password [clickable]
#   ── BUTTONS ────────────────────
#   👁  <button>     button    Sign In [clickable]
#      <button>     button    Forgot password?

Warning

inspect adds a 500 ms settle delay after navigation to let JS-heavy SPAs finish rendering. For faster pages you can increase --log-level debug to see timing details.