CLI Reference

Drive webrain by hand — every engine and tool has a CLI twin.

Help

webrain --help lists every command plus every environment variable the binary reads, grouped (attach/engines, stealth, network, MCP transport, vault, SERP tiers, agent, local AI, logging). The defaults and the long explanations live in Environment Variables; webrain help env prints just that section and webrain <command> --help prints one command’s flags.

Commands

Command	Description
`webrain mcp [--http <port>]`	Start the MCP server (stdio, or HTTP on a port)
`webrain install [--force] [--engine chrome\|obscura\|lightpanda\|whisper\|vision\|watch] [--stealth] [--model NAME\|ID] [--model-update]`	Download a browser engine, or the local AI stack: `watch` = ffmpeg+yt-dlp+whisper-cli+model, `whisper` = STT GGUF model, `vision` = llama-server + one local vision model (ids in the installation guide)
`webrain uninstall vision [--model ID \| --all]`	Remove one installed local vision model, or all of them (also clears a legacy single-model install)
`webrain upgrade`	Update to the latest release
`webrain diff <a> <b> [--max N] [--json]`	What changed between two pages, or a page and a saved baseline. Either side is an http(s) URL or a local file; no browser. Exit 1 when they differ
`webrain chat "<prompt>" [--provider P] [--model ID] [--key-from VAR] [--base-url URL] [--search] [--serve [--port N]] [--max-output-tokens N] [--timeout SECS] [--yes] [--json] [--no-stream] [--print-config]`	One Copilot agent turn on your own model key, with webrain’s own MCP tools attached (it spawns `webrain mcp` itself). `--search` grounds the turn on live web results first. `--serve` runs the same session behind a page at `http://127.0.0.1:8787/` (SSE event stream, permission modal; loopback only). Exit 0 completed, 1 turn failed, 2 could not start. `--print-config` resolves and prints the provider with the key redacted, offline — see Chat
`webrain obscura [--port N]`	Spawn the Obscura CDP server (default 9224)
`webrain lightpanda [--port N]`	Spawn the Lightpanda CDP server (default 9225)
`webrain launch <service> <profile> [url] [--headless] [--port N]`	Spawn a stealth Chrome with a persistent per-account profile
`webrain login <service> <profile> [url] [--port N]`	Launch + attach for interactive login
`webrain cookies [--port N] [--out file]`	Export cookies
`webrain setcookies <file>`	Import cookies
`webrain vault set\|list\|user\|rm`	Manage encrypted credentials (hidden prompts)
`webrain fetch <url>`	Attach to `CDP_URL` and fetch
`webrain watch <url\|file> [--detail transcript\|efficient\|balanced] [--max-frames N] [--resolution W] [--start S] [--end E] [--out-dir D] [--no-whisper] [--stt whisper\|gemini] [--vision]`	Transcript + frames for any video (no browser); `--vision` adds text captions (cloud key or local Qwen3-VL-2B)
`webrain screenshot <url>`	Screenshot (single or full page)
`webrain spider <url> [--depth N --pages N --respect-robots --json-urls --dfs --bestfirst --keywords k1,k2 --no-same-domain --discover-only]`	Crawl
`webrain serp "query" [--engine duckduckgo\|bing\|google\|brave\|yahoo\|baidu\|yandex\|auto] [--limit N] [--page N] [--safe] [--region R] [--http] [--no-fallback] [--json] [--proxy URL] [--headless] [--fresh] [--pipe] [--hold]`	Structured SERP JSON (`position`/`title`/`url`/`domain`/`snippet`) — the CLI twin of `webrain_serp`. `duckduckgo`/`bing`/`yahoo`/`baidu`/`yandex`/`auto` are pure HTTP (yahoo keeps a cookie jar; baidu and yandex report a challenge page as a failure, never as `0 results`); `google` auto-launches a warm persistent-profile Chrome, `brave` uses the connected CDP engine. `--http` never touches a browser at all (no render, no guest launch, even when `CDP_URL` is set) — the mode for `--engine bing --limit 50`, which otherwise pays a Chrome launch for the same rows. `--limit` clamps 1..=100, `--page` is 0-based. `--fresh` starts a brand-new profile (forces the consent modal), `--pipe` launches it with no open debugging port, `--hold` keeps the browser open after the search. `--stealth` is accepted for compat and is a no-op
`webrain click <i>` / `webrain type <i> <text>` / `webrain eval <js>`	Drive the `CDP_URL` backend
`webrain doctor`	Full install diagnosis — version, MCP server, CDP ports (9222/9224/9225), engine discovery, vault, `recommend`

Index-driven interaction

webrain click <i> / webrain type <i> <text> / webrain eval <js> attach to the CDP_URL backend and operate on element indices — the same elements[] array that webrain_observe / webrain_navigate return over MCP:

webrain launch <service> <profile> <url>   # real Chrome on a persistent profile
webrain click 3                            # click element #3
webrain type 5 "text"                      # type into element #5
webrain eval 'document.querySelector("#email").value'

Get the element list from the MCP side (webrain_observe what=state or what=a11y returns elements[] with these indices), or run webrain fetch <url> to load a page and see its element count. For CSS selectors use the MCP tools instead: webrain_observe what=html accepts a selector, webrain_extract mode=schema is driven entirely by selectors, and webrain_interact action=wait accepts a selector.

`webrain doctor`

Exit codes: 0 healthy, 2 broken. Checks the install end to end — engines, MCP server, CDP ports, vault — and prints a recommend line. The first step in any troubleshooting session. --doctor is an alias flag.

Getting Started

MCP Clients

Concepts

Agent

Guides

Comparisons

Reference

Project

CLI Reference

CLI Reference

Help

Commands

Index-driven interaction

`webrain doctor`

​CLI Reference

​Help

​Commands

​Index-driven interaction

​webrain doctor

CLI Reference

Help

Commands

Index-driven interaction

`webrain doctor`