browser_control/cli/
agent_instructions.rs

1//! Canonical instructions for agents using `browser-control`.
2
3pub const AGENT_INSTRUCTIONS: &str = r#"browser-control agent instructions
4
5Use the highest-level browser-control primitive available.
6- If MCP tools are available, prefer them over shell commands.
7- If MCP tools are not available, use the `browser-control` CLI.
8- Do not drive raw CDP/BiDi, scrape browser profile databases, or launch a separate browser unless browser-control lacks the needed primitive.
9- Use `--json` for CLI output that another tool or agent will parse.
10
11Browser selection
12- Select a browser with `browser_select` in MCP, or with CLI `-b/--browser`, `$BROWSER_CONTROL`, or `browser-control set default <selector>`.
13- Selectors may be a kind (`chrome`, `edge`, `chromium`, `brave`, `firefox`), a friendly name from `list-running`, an absolute executable path, or a CDP/BiDi endpoint URL.
14- If nothing is running, use `browser-control start <kind>`. It reuses a persistent per-kind profile so login state survives.
15
16Tabs
17- Prefer tab primitives over target IDs:
18  MCP: `browser_tab_list`, `browser_tab_new`, `browser_tab_select`, `browser_tab_close`.
19  CLI: `browser-control tab open <browser>/<name> [url]`, `tab list <browser> --all`, `tab adopt <browser>/<name> <target-id>`.
20- For repeatable work, create or select a named tab, then address it as `<browser>/<tab>` in page-context CLI commands.
21- Use target IDs only to adopt an existing unnamed tab or as a last-resort diagnostic.
22- Browser-wide operations do not take tab names. Page-context operations do.
23
24Page and network work
25- Navigate and inspect with MCP primitives first: `browser_navigate`, `browser_get_html`, `browser_take_screenshot`, `browser_select_element`.
26- CLI navigation: `browser-control tab open <browser>/<name> <url>` opens or navigates a named tab (re-running with a new url navigates the existing tab). This is how you go to a URL from the CLI — never navigate by evaling `location.href`, which bypasses the tab registry and races the page load.
27- Fetch authenticated APIs with `browser_fetch` or `browser-control fetch`; this runs inside the browser context so cookies, Origin, CORS, and the browser TLS stack apply.
28- Read/write storage with `browser_storage_get` / `browser_storage_set` or `browser-control storage`.
29- Evaluate JavaScript with `browser-control eval` when no MCP primitive fits.
30- Auth-sensitive reads reload HTTP(S) pages older than 10 minutes before evaluating so SSO can refresh tokens. CLI callers can override with `--max-age 1h`; MCP callers can pass `max_age`.
31
32Cookies and login
33- Wait for login with `browser_wait_for_cookie` or `browser-control wait-for-cookie --domain <regex> --name <regex>`.
34- Add `--validate-url <url>` when the cookie alone is not enough and an authenticated endpoint must return 2xx.
35- Export cookies with `browser_cookies` or `browser-control cookies`; use `--format netscape -o cookies.txt` for curl, wget, or yt-dlp.
36
37MCP server setup
38- Configure the host with command `browser-control` and args `["mcp"]`.
39- Set `BROWSER_CONTROL` in the MCP host env to scope that server to one browser, or rely on `browser-control set default`.
40- Playwright-sidecar tools (`browser_snapshot`, `browser_click`, `browser_type`, `browser_hover`, `browser_drag`, `browser_press_key`, `browser_wait_for`, `browser_pdf_save`) require Node tooling and CDP browsers. On Firefox, use the engine-agnostic primitives instead.
41
42Recovery
43- If a tab is gone or hung, list tabs, select another tab, or create a fresh named tab and retry.
44- URL regex selectors are unanchored unless you add `^` or `$`.
45"#;
46
47pub fn print() {
48    println!("{AGENT_INSTRUCTIONS}");
49}
browser_control/cli/agent_instructions.rs

browser_control/cli/
agent_instructions.rs
