# Omnibot Command Reference

This is a lookup table, not a behavior guide. Choose behavior from `operation-patterns.md`, use `session-and-tabs.md` for targeting, and use `fallback-operations.md` before dropping to lower tiers.

## Runtime & Status

### doctor

Purpose: Check daemon and browser extension health.

```bash
omnibot doctor
```

Preferred pattern: See `runtime-and-status.md#startup-check`.
Fallback relation: Not a fallback command.

### status

Purpose: Show daemon status only (lighter than `doctor`).

```bash
omnibot status
```

Preferred pattern: See `runtime-and-status.md#daemon-lifecycle`.
Fallback relation: Not a fallback command.

### start

Purpose: Start the daemon in the background.

```bash
omnibot start
```

Equivalent to: `omnibot daemon start`

### stop

Purpose: Stop the running daemon.

```bash
omnibot stop
```

Equivalent to: `omnibot daemon stop`

### run

Purpose: Run the daemon in the foreground.

```bash
omnibot run
```

Equivalent to: `omnibot daemon run`

### tabs

Purpose: List connected browser tabs and discover tab ids.

```bash
omnibot tabs
```

Preferred pattern: See `session-and-tabs.md#tab-explicit`.
Fallback relation: Not a fallback command.

### license status

Purpose: Check license state.

```bash
omnibot license status
```

Preferred pattern: See `runtime-and-status.md#startup-check`.
Fallback relation: Not a fallback command.

## Reading

### read

Purpose: Read clean rendered page text/Markdown from an existing tab or a temporary URL tab.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --timeout 120 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot read --screens 3 https://example.com/article
OMNIBOT_SESSION_TOKEN=research omnibot read --json --screens 5 --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#read` and `operation-patterns.md#extraction`.
Fallback relation: Prefer for page content. Use `snapshot -i` when the next step is action planning, and `get`/`is`/`wait` for narrow state verification.

### snapshot -i

Purpose: Read accessibility tree and produce actionable `@eN` refs.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i -c -d 4 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i -s "#main" -u --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#click`, `operation-patterns.md#fill`, and `session-and-tabs.md#ref-scope`.
Fallback relation: Tier 2 after semantic find.

### get

Purpose: Read one value or element state without dumping the page.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get text "#main" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get html "#main" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get value "input[name=email]" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get attr "a.login" href --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get count ".item" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get box "#submit" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot get styles "#submit" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#read` and `operation-patterns.md#extraction`.
Fallback relation: Selector tier for reading; escalate only if unavailable.

### is

Purpose: Check element state.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot is visible "#submit" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "#submit" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot is checked "#agree" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#read` and `operation-patterns.md#select--check`.
Fallback relation: Prefer before visual or JavaScript checks.

## Actions

### click

Purpose: Click an element by `@eN` ref or selector.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4 --new-tab
OMNIBOT_SESSION_TOKEN=checkout omnibot click "button[type=submit]" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#click`.
Fallback relation: Tier 2 with refs, Tier 3 with selector.

### dblclick

Purpose: Double-click an element by `@eN` ref or selector.

```bash
OMNIBOT_SESSION_TOKEN=editor omnibot dblclick --tab-id <TAB_ID> @e7
```

Preferred pattern: See `operation-patterns.md#click`.
Fallback relation: Prefer semantic or snapshot first; then selector.

### fill

Purpose: Replace an input value.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot fill --tab-id <TAB_ID> @e2 "a@b.com"
OMNIBOT_SESSION_TOKEN=checkout omnibot fill "input[name=email]" "a@b.com" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#fill`.
Fallback relation: Tier 2 with refs, Tier 3 with selector.

### type

Purpose: Type text into an element.

```bash
OMNIBOT_SESSION_TOKEN=search omnibot type --tab-id <TAB_ID> @e3 "omnibot"
```

Preferred pattern: See `operation-patterns.md#fill`.
Fallback relation: Use after fill is not appropriate or focus is needed.

### press

Purpose: Press a key in the target tab.

```bash
OMNIBOT_SESSION_TOKEN=search omnibot press Enter --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#fill` and `operation-patterns.md#wait`.
Fallback relation: Not a fallback by itself; verify after pressing.

### hover

Purpose: Hover an element by ref or selector.

```bash
OMNIBOT_SESSION_TOKEN=menu omnibot hover --tab-id <TAB_ID> @e5
```

Preferred pattern: Observe menu state, hover, then verify visible options.
Fallback relation: Use mouse move only if hover fails.

### focus

Purpose: Focus an element by selector.

```bash
OMNIBOT_SESSION_TOKEN=form omnibot focus "input[name=email]" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#fill`.
Fallback relation: Selector tier before keyboard/type fallback.

### select

Purpose: Select an option in a dropdown.

```bash
OMNIBOT_SESSION_TOKEN=form omnibot select @e5 "US" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#select--check`.
Fallback relation: Prefer refs/selectors before JavaScript value changes. For CSS-only dropdowns whose options are absent from `snapshot -i`, see `fallback-operations.md#css-only-dropdown-javascript-fallback`.

### check / uncheck

Purpose: Set checkbox state.

```bash
OMNIBOT_SESSION_TOKEN=form omnibot check @e6 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=form omnibot uncheck @e6 --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#select--check`.
Fallback relation: Verify with `is checked` before and after.

### scroll / scrollintoview

Purpose: Scroll page or element.

```bash
OMNIBOT_SESSION_TOKEN=read omnibot scroll down 500 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=read omnibot scroll down 500 --selector "#list" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=read omnibot scrollintoview @e7 --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#read` and `operation-patterns.md#extraction`.
Fallback relation: DOM or mouse scroll only after standard scroll fails.

### drag

Purpose: Drag from one element to another.

```bash
OMNIBOT_SESSION_TOKEN=board omnibot drag @e8 @e9 --tab-id <TAB_ID>
```

Preferred pattern: Observe source and target, drag, verify position/state.
Fallback relation: Mouse drag is Tier 5 if element drag fails.

### upload

Purpose: Upload a local file through a file input.

```bash
OMNIBOT_SESSION_TOKEN=form omnibot upload "input[type=file]" /path/to/file.png --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#upload`.
Fallback relation: Use JavaScript only if native upload cannot reach the input.

## Semantic Find

Semantic find is Tier 1 for operating by meaning.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find text "Sign in" --action click --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find label "Email" --action fill --action-value "a@b.com" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find placeholder "Search" --action type --action-value "omnibot" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find testid submit-button --action click --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find nth ".card" 2 --action click --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#click` and `operation-patterns.md#fill`.
Fallback relation: Tier 1. Explain failure before using refs, selectors, DOM, mouse, JavaScript, or CDP.

## Fallback Actions

### mouse

Purpose: Coordinate-based mouse operations.
Usage tier: Tier 5 fallback only.

```bash
OMNIBOT_SESSION_TOKEN=repair omnibot mouse click --x 100 --y 200 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot mouse click --x 100 --y 200 --click-count 2 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot mouse move --x 50 --y 60 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot mouse scroll --x 100 --y 200 --dy 500 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot mouse drag --from-x 10 --from-y 20 --to-x 100 --to-y 200 --tab-id <TAB_ID>
```

Preferred pattern: See `fallback-operations.md#mouse-fallback`.
Fallback relation: After semantic, refs, selector, and DOM fail.

### dom

Purpose: Interact with visible DOM node ids returned by `dom visible`.
Usage tier: Tier 4 fallback only.

```bash
OMNIBOT_SESSION_TOKEN=repair omnibot dom visible --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot dom click n1 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot dom dblclick n1 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot dom scroll n1 --dy 800 --tab-id <TAB_ID>
```

Preferred pattern: See `fallback-operations.md#dom-fallback`.
Fallback relation: After selector failure and before mouse fallback.

### execute-js

Purpose: Run arbitrary JavaScript in the page.
Usage tier: Tier 6 fallback only. Do not use first.

```bash
OMNIBOT_SESSION_TOKEN=repair omnibot execute-js "return location.href" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=repair omnibot execute-js --file /tmp/repair.js --tab-id <TAB_ID>
```

Preferred pattern: See `fallback-operations.md#javascript-fallback`.
Fallback relation: After semantic, refs, selector, DOM, and mouse are insufficient. Valid examples include CSS-only dropdowns where the trigger exists but option refs are absent from `snapshot -i`.

### cdp

Purpose: Send raw Chrome DevTools Protocol commands.
Usage tier: Tier 7 fallback and inspection only.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot cdp Runtime.evaluate '{"expression":"document.title"}' --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot cdp DOM.getDocument '{"depth":1}' --tab-id <TAB_ID>
```

Preferred pattern: See `fallback-operations.md#raw-cdp-fallback` and `debugging-and-evidence.md#cdp-inspection`.
Fallback relation: Last resort.

## Navigation & Tabs

### navigate / open / goto

Purpose: Navigate or open pages. These commands create or use CLI target state; record the resulting tab id and use `--tab-id` afterward.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com
OMNIBOT_SESSION_TOKEN=research omnibot navigate --same-tab https://example.com
OMNIBOT_SESSION_TOKEN=research omnibot open https://example.com
OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com
```

Preferred pattern: See `operation-patterns.md#navigation` and `session-and-tabs.md#tab-explicit`.
Fallback relation: Verify with `get url --tab-id <TAB_ID>` before continuing.

### close / back / forward / reload / pushstate

Purpose: Change tab lifecycle or history state.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot close <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot back --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot forward --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot reload --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot pushstate /dashboard --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#navigation`.
Fallback relation: Verify URL or page state after the action.

### tab

Purpose: Manage browser tabs.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot tab list
OMNIBOT_SESSION_TOKEN=research omnibot tab new https://docs.example.com --label docs
OMNIBOT_SESSION_TOKEN=research omnibot tab close docs
```

Preferred pattern: See `session-and-tabs.md#tab-explicit`.
Removed: `tab switch` and `tab focus` are no longer available. Use explicit `--tab-id` on every page-state command.

### window / frame

Purpose: Manage windows and frames.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot window new
OMNIBOT_SESSION_TOKEN=research omnibot frame main
```

## Waiting & Batch

### wait

Purpose: Wait for time, selector, text, URL, load state, or JavaScript condition.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot wait 500 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait "#ready" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait "#spinner" --state hidden --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait --text "Welcome" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load domcontentloaded --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load networkidle --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait --fn "window.appReady === true" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#wait`.
Fallback relation: Prefer over shell sleep.

### batch

Purpose: Send short command arrays as JSON or from a file.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"snapshot","interactive":true}]' --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot batch --file /tmp/omnibot-batch.json --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#batch`.
Fallback relation: Not a substitute for verification.

## Debugging

### screenshot

Purpose: Capture visual evidence from a browser tab.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot screenshot --tab-id <TAB_ID> -o /tmp/omni-shot.png
OMNIBOT_SESSION_TOKEN=debug omnibot screenshot --annotate --tab-id <TAB_ID> -o /tmp/omni-annotated.png
```

Preferred pattern: See `debugging-and-evidence.md#screenshot`.
Fallback relation: Evidence collection, not operation fallback.

### console

Purpose: Read or clear browser console evidence.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot console logs --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot console errors --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot console clear --tab-id <TAB_ID>
```

Preferred pattern: See `debugging-and-evidence.md#console`.
Fallback relation: Evidence collection, not operation fallback.

### network

Purpose: Read browser network evidence.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot network logs --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot network summary --tab-id <TAB_ID>
```

Preferred pattern: See `debugging-and-evidence.md#network`.
Fallback relation: Evidence collection, not operation fallback.

## Browser Capabilities

### clipboard

Purpose: Read or write browser clipboard.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot clipboard read --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot clipboard write "text" --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#extraction`.
Fallback relation: Use only when clipboard is part of the browser task.

### viewport

Purpose: Read or set viewport size.

```bash
OMNIBOT_SESSION_TOKEN=visual omnibot viewport get --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=visual omnibot viewport set 1280 720 --tab-id <TAB_ID>
```

Preferred pattern: Set explicit viewport before visual verification if layout matters.
Fallback relation: Not a fallback command.

### assets

Purpose: List or export page resources.

```bash
OMNIBOT_SESSION_TOKEN=extract omnibot assets list --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=extract omnibot assets export -o /tmp/assets.zip --tab-id <TAB_ID>
```

Preferred pattern: See `operation-patterns.md#extraction`.
Fallback relation: Use after page content indicates assets are needed.

## Visibility & Sessions

### visibility

Purpose: Inspect, set, or launch automation browser visibility mode.

```bash
omnibot visibility status
omnibot visibility set background
omnibot visibility set visible
omnibot visibility set headless --user-data-dir /tmp/omnibot-headless
omnibot visibility launch headless --user-data-dir /tmp/omnibot-headless
```

Preferred pattern: See `session-and-tabs.md#visibility`.
Fallback relation: Headless does not inherit existing user login state.

### browser

Purpose: Manage browser runtime ownership.

```bash
OMNIBOT_SESSION_TOKEN=research omnibot browser list
OMNIBOT_SESSION_TOKEN=research omnibot browser current
OMNIBOT_SESSION_TOKEN=research omnibot browser claim 123
OMNIBOT_SESSION_TOKEN=research omnibot browser release 123
```

Preferred pattern: See `session-and-tabs.md#browser-claimrelease`.
Fallback relation: Use in multi-browser or multi-runtime scenarios.

### session

Purpose: Name or list sessions.

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot session name "checkout"
OMNIBOT_SESSION_TOKEN=checkout omnibot session list
```

Preferred pattern: See `session-and-tabs.md#session-first`.
Fallback relation: Not a fallback command.

## Recording & Trace

### record / replay / trace

Purpose: Capture, replay, or trace workflows for evidence.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot record start
OMNIBOT_SESSION_TOKEN=debug omnibot record stop -o flow.json
OMNIBOT_SESSION_TOKEN=debug omnibot replay flow.json
OMNIBOT_SESSION_TOKEN=debug omnibot trace start
OMNIBOT_SESSION_TOKEN=debug omnibot trace stop -o trace.zip
```

Preferred pattern: See `debugging-and-evidence.md#record-and-replay` and `debugging-and-evidence.md#trace`.
Fallback relation: Evidence collection, not operation fallback.

## Skills & License

### skills install / skills path

Purpose: Install packaged omnibot skills or show the packaged skills path.

```bash
omnibot skills install --agent hermes --profile nuwa
omnibot skills install --agent opencode
omnibot skills install --agent claude
omnibot skills install --agent codex
omnibot skills path
```

Preferred pattern: See `runtime-and-status.md#skills-path`.
Fallback relation: Not a fallback command.

### license status

Purpose: Inspect license status.

```bash
omnibot license status
```

Preferred pattern: See `runtime-and-status.md#startup-check`.
Fallback relation: Not a fallback command.
