1# Raw CDP & Python Session Reference
2 
3The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP when you need browser-level control the CLI doesn't expose — activating a tab so the user sees it, intercepting network requests, emulating devices, or working with Chrome target IDs directly.
4 
5## How the Python session works
6 
7`browser-use python "statement"` executes one Python statement per call. Variables persist across calls — set a value in one call, use it in the next.
8 
9A `browser` object is pre-injected with sync wrappers for common operations (`browser.goto()`, `browser.click()`, etc.). For anything beyond those, two internals give you full access:
10 
11- `browser._run(coroutine)` — run any async coroutine synchronously (60s timeout)
12- `browser._session` — the raw `BrowserSession` with full CDP client access
13 
14## Getting a CDP client
15 
16```bash
17browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
18```
19 
20After this, `cdp` persists across calls. Use `cdp.cdp_client.send.<Domain>.<method>()` for any CDP command and `cdp.session_id` for the session parameter.
21 
22## Recipes
23 
24### Activate a tab (make it visible to the user)
25 
26The CLI's `tab switch` only changes the agent's internal focus — Chrome's visible tab doesn't change. To actually show the user a specific tab:
27 
28```bash
29# Get all targets to find the target ID
30browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
31browser-use python "print([(i, t.url) for i, t in enumerate(targets)])"
32 
33# Activate target at index 1 so the user sees it
34browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session(target_id=None, focus=False))"
35browser-use python "browser._run(cdp.cdp_client.send.Target.activateTarget(params={'targetId': targets[1].target_id}))"
36```
37 
38### List all tabs with target IDs
39 
40```bash
41browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
42browser-use python "
43for i, t in enumerate(targets):
44    print(f'{i}: {t.target_id[:12]}... {t.url}')
45"
46```
47 
48### Run JavaScript and get the result
49 
50```bash
51browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
52browser-use python "result = browser._run(cdp.cdp_client.send.Runtime.evaluate(params={'expression': 'document.title', 'returnByValue': True}, session_id=cdp.session_id))"
53browser-use python "print(result['result']['value'])"
54```
55 
56### Emulate a mobile device
57 
58```bash
59browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
60browser-use python "browser._run(cdp.cdp_client.send.Emulation.setDeviceMetricsOverride(params={'width': 375, 'height': 812, 'deviceScaleFactor': 3, 'mobile': True}, session_id=cdp.session_id))"
61```
62 
63### Get cookies via CDP
64 
65```bash
66browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
67browser-use python "cookies = browser._run(cdp.cdp_client.send.Network.getCookies(params={}, session_id=cdp.session_id))"
68browser-use python "print(cookies)"
69```
70 
71## Tips
72 
73- Each `browser-use python` call is one statement. Multi-line strings work for `for` loops and `if` blocks, but you can't mix statements and expressions. Use multiple calls.
74- Variables persist: set `cdp = ...` in one call, use `cdp` in the next.
75- The `browser._run()` bridge has a 60-second timeout. For long operations, increase it or use the async internals directly.
76- All CDP domains are available via `cdp.cdp_client.send.<Domain>.<method>()`. See the [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/) for the full API.
77