cli-reference.md

dom0 — CLI Reference

Complete reference for all dom0 commands.

Global Options

bash
dom0 [options] <command>

Options:
  --json       Output in JSON format
  -v, --verbose    Verbose output
  -V, --version    Show version
  -h, --help       Show help

Navigate to a URL.

bash
dom0 navigate <url>
dom0 goto <url>  # Alias

Examples:

bash
dom0 navigate https://google.com
dom0 goto example.com  # https:// added automatically

Output:

Navigated to https://google.com

back

Go back in browser history.

bash
dom0 back

Output:

Navigated back

forward

Go forward in browser history.

bash
dom0 forward

Output:

Navigated forward

Page State Commands

snapshot

Get the current page state with element refs.

bash
dom0 snapshot [options]

Options:
  --full    Include non-interactable elements

Examples:

bash
dom0 snapshot
dom0 snapshot --full
dom0 snapshot --json

Output:

URL: https://example.com/login
Title: Login - Example

@d1  button "Sign In"
@d2  textbox "Email"
@d3  textbox "Password"
@d4  link "Forgot password?"
@d5  checkbox "Remember me"

JSON Output:

json
{
  "success": true,
  "data": {
    "url": "https://example.com/login",
    "title": "Login - Example",
    "refs": {
      "d1": { "alias": "d1", "role": "button", "name": "Sign In" },
      "d2": { "alias": "d2", "role": "textbox", "name": "Email" }
    },
    "tree": "@d1  button \"Sign In\"\n@d2  textbox \"Email\"..."
  }
}

screenshot

Capture the current page.

bash
dom0 screenshot [options]

Options:
  --output, -o <path>  Save to file (default: prints base64)
  --full               Full page screenshot

Examples:

bash
dom0 screenshot -o page.png
dom0 screenshot --full -o full-page.png
dom0 screenshot --json  # Returns base64

Output:

Screenshot saved to page.png

Interaction Commands

click

Click an element by ref.

bash
dom0 click <ref>

Examples:

bash
dom0 click @d1
dom0 click d1  # @ is optional

Output:

Clicked @d1 (button "Sign In")

type

Type text into an input element.

bash
dom0 type <ref> <text>

Examples:

bash
dom0 type @d2 "user@example.com"
dom0 type @d3 'my password'

Output:

Typed into @d2 (textbox "Email")

fill

Clear input and type new text.

bash
dom0 fill <ref> <text>

Examples:

bash
dom0 fill @d2 "new@example.com"

Output:

Filled @d2 (textbox "Email")

hover

Hover over an element.

bash
dom0 hover <ref>

Examples:

bash
dom0 hover @d4

Output:

Hovered @d4 (link "Forgot password?")

focus

Focus an element.

bash
dom0 focus <ref>

Examples:

bash
dom0 focus @d2

Output:

Focused @d2 (textbox "Email")

press

Press a keyboard key.

bash
dom0 press <key>

Supported Keys:

  • Enter, Tab, Escape, Backspace, Delete
  • ArrowUp, ArrowDown, ArrowLeft, ArrowRight
  • Home, End, PageUp, PageDown
  • F1-F12
  • Modifiers: Shift, Control, Alt, Meta

Examples:

bash
dom0 press Enter
dom0 press Tab
dom0 press Escape

Output:

Pressed Enter

select

Select an option from a dropdown.

bash
dom0 select <ref> <value>

Examples:

bash
dom0 select @d6 "option1"
dom0 select @d6 "United States"

Output:

Selected "option1" in @d6 (combobox "Country")

scroll

Scroll the page or element.

bash
dom0 scroll <direction> [options]

Directions: up, down, left, right

Options:
  --amount <px>   Pixels to scroll (default: 300)
  --ref <ref>     Scroll within element

Examples:

bash
dom0 scroll down
dom0 scroll up --amount 500
dom0 scroll down --ref @d10  # Scroll within element

Output:

Scrolled down 300px

Data Extraction Commands

get-text

Get text content of an element.

bash
dom0 get-text <ref>

Examples:

bash
dom0 get-text @d7

Output:

Welcome to our site!

get-attr

Get an attribute value from an element.

bash
dom0 get-attr <ref> <attribute>

Examples:

bash
dom0 get-attr @d4 href
dom0 get-attr @d2 placeholder

Output:

/forgot-password

get-value

Get the current value of an input element.

bash
dom0 get-value <ref>

Examples:

bash
dom0 get-value @d2

Output:

user@example.com

Wait Commands

wait

Wait for a condition.

bash
dom0 wait [options]

Options:
  --selector <css>   Wait for CSS selector
  --text <text>      Wait for text to appear
  --timeout <ms>     Max wait time (default: 30000)
  --hidden           Wait for element to be hidden

Examples:

bash
dom0 wait --selector ".loaded"
dom0 wait --text "Success"
dom0 wait --selector ".modal" --hidden
dom0 wait --timeout 5000 --selector "#result"

Output:

Found selector ".loaded" (waited 1.2s)

Tab Management Commands

tabs

List all open tabs.

bash
dom0 tabs

Output:

Tabs:
  [1] Google (https://google.com) *
  [2] GitHub (https://github.com)
  [3] Example (https://example.com)

* = active tab

tab-switch

Switch to a different tab.

bash
dom0 tab-switch <tab-id>

Examples:

bash
dom0 tab-switch 2

Output:

Switched to tab 2 (GitHub)

tab-new

Open a new tab.

bash
dom0 tab-new [url]

Examples:

bash
dom0 tab-new
dom0 tab-new https://example.com

Output:

Opened new tab (id: 4)

tab-close

Close the current or specified tab.

bash
dom0 tab-close [tab-id]

Examples:

bash
dom0 tab-close
dom0 tab-close 3

Output:

Closed tab 3

Daemon Commands

status

Check connection status.

bash
dom0 status

Output:

Daemon: Running (port 9222)
Extension: Connected (v0.1.0)
Active tab: Google (https://google.com)

ping

Test extension connection.

bash
dom0 ping

Output:

Pong! (42ms)

stop

Stop the background daemon.

bash
dom0 stop

Output:

Daemon stopped

Error Messages

Common Errors

ErrorCauseSolution
Unknown ref: @d99Ref doesn't existRun dom0 snapshot to get current refs
Element @d3 is stalePage changed since snapshotRun dom0 snapshot again
Extension not connectedExtension disconnectedRefresh extension in chrome://extensions
No active tabNo browser tab openOpen Chrome and navigate to a page
Connection refusedDaemon not runningDaemon auto-starts; check if Chrome is open
Request timeoutCommand took too longIncrease timeout or simplify page

Error Format

bash
# Text mode
Error: Unknown ref: @d99

# JSON mode
{
  "success": false,
  "error": "Unknown ref: @d99"
}

Usage Patterns

Login Flow

bash
dom0 navigate https://example.com/login
dom0 snapshot
dom0 type @d2 "user@example.com"
dom0 type @d3 "password123"
dom0 click @d1
dom0 wait --text "Welcome"
dom0 snapshot

Form Filling

bash
dom0 snapshot
dom0 fill @d2 "John Doe"
dom0 fill @d3 "john@example.com"
dom0 select @d4 "United States"
dom0 click @d5  # Checkbox
dom0 click @d6  # Submit button

Data Extraction

bash
dom0 navigate https://example.com/products
dom0 snapshot --json > page.json
dom0 get-text @d10
dom0 get-attr @d11 href
dom0 screenshot -o products.png

Multi-Tab Workflow

bash
dom0 tab-new https://google.com
dom0 snapshot
dom0 type @d1 "search query"
dom0 press Enter
dom0 tabs
dom0 tab-switch 1