1---
2name: chrome-cdp
3description: Interact with local Chrome browser session (only on explicit user approval after being asked to inspect, debug, or interact with a page open in Chrome)
4---
5 
6# Chrome CDP
7 
8Lightweight Chrome DevTools Protocol CLI. Connects directly via WebSocket — no Puppeteer, works with 100+ tabs, instant connection.
9 
10## Prerequisites
11 
12- Chrome (or Chromium, Brave, Edge, Vivaldi) with remote debugging enabled: open `chrome://inspect/#remote-debugging` and toggle the switch
13- Node.js 22+ (uses built-in WebSocket)
14- If your browser's `DevToolsActivePort` is in a non-standard location, set `CDP_PORT_FILE` to its full path
15 
16## Commands
17 
18All commands use `scripts/cdp.mjs`. The `<target>` is a **unique** targetId prefix from `list`; copy the full prefix shown in the `list` output (for example `6BE827FA`). The CLI rejects ambiguous prefixes.
19 
20### List open pages
21 
22```bash
23scripts/cdp.mjs list
24```
25 
26### Take a screenshot
27 
28```bash
29scripts/cdp.mjs shot <target> [file]    # default: screenshot-<target>.png in runtime dir
30```
31 
32Captures the **viewport only**. Scroll first with `eval` if you need content below the fold. Output includes the page's DPR and coordinate conversion hint (see **Coordinates** below).
33 
34### Accessibility tree snapshot
35 
36```bash
37scripts/cdp.mjs snap <target>
38```
39 
40### Evaluate JavaScript
41 
42```bash
43scripts/cdp.mjs eval <target> <expr>
44```
45 
46> **Watch out:** avoid index-based selection (`querySelectorAll(...)[i]`) across multiple `eval` calls when the DOM can change between them (e.g. after clicking Ignore, card indices shift). Collect all data in one `eval` or use stable selectors.
47 
48### Other commands
49 
50```bash
51scripts/cdp.mjs html    <target> [selector]   # full page or element HTML
52scripts/cdp.mjs nav     <target> <url>         # navigate and wait for load
53scripts/cdp.mjs net     <target>               # resource timing entries
54scripts/cdp.mjs click   <target> <selector>    # click element by CSS selector
55scripts/cdp.mjs clickxy <target> <x> <y>       # click at CSS pixel coords
56scripts/cdp.mjs type    <target> <text>         # Input.insertText at current focus; works in cross-origin iframes unlike eval
57scripts/cdp.mjs loadall <target> <selector> [ms]  # click "load more" until gone (default 1500ms between clicks)
58scripts/cdp.mjs evalraw <target> <method> [json]  # raw CDP command passthrough
59scripts/cdp.mjs open    [url]                  # open new tab (each triggers Allow prompt)
60scripts/cdp.mjs stop    [target]               # stop daemon(s)
61```
62 
63## Coordinates
64 
65`shot` saves an image at native resolution: image pixels = CSS pixels × DPR. CDP Input events (`clickxy` etc.) take **CSS pixels**.
66 
67```
68CSS px = screenshot image px / DPR
69```
70 
71`shot` prints the DPR for the current page. Typical Retina (DPR=2): divide screenshot coords by 2.
72 
73## Tips
74 
75- Prefer `snap --compact` over `html` for page structure.
76- Use `type` (not eval) to enter text in cross-origin iframes — `click`/`clickxy` to focus first, then `type`.
77- Chrome shows an "Allow debugging" modal once per tab on first access. A background daemon keeps the session alive so subsequent commands need no further approval. Daemons auto-exit after 20 minutes of inactivity.
78