cdp documentation
Drive Chrome from the command line to capture network traffic, extract rendered pages, and write browser automation that runs as tests.
This repository is built on the Chrome DevTools Protocol. Everything here drives a real browser, so JavaScript runs, single-page applications render, and authenticated sessions work.
There are three entry points, and which one you want depends on how durable the work needs to be.
cdp — generalized browser scripting
The interactive and agent-driven surface. Attach to a browser you are already logged into, drive it from a prompt or over MCP, capture traffic while you click, extract or render what you find. Reach for it when the work is exploratory, or when getting to the interesting page needs a human or an agent first.
cdp -headless -url https://example.com -render body
→ The cdp guide · Quickstart ·
Capture traffic · MCP server
cdpscript — Unix-like tools for browser operations
The durable command-line surface. A script is a txtar archive that runs the
same way every time, takes arguments, writes artifacts, and exits with a status
a shell can branch on. Give it a shebang line and chmod +x and it is a Unix
tool — one you can put on $PATH, in a pipeline, or in a Makefile.
#!/usr/bin/env cdpscript
# greet - print the title of a page
-- main.cdp --
goto $ARG1
title
./greet.cdpscript https://example.com # or: cdpscript -o ./artifacts greet.cdpscript
cdpscripttest — Go-native browser testing
The testing surface. The same archives run under go test, so a script that
reproduces a bug becomes the regression test for it without being rewritten.
Fixtures travel inside the archive, and browser tests sit behind a build tag so
an ordinary go test ./... needs no browser.
cdpscripttest.RunCDPScript(t.Context(), "greet.txtar", opts)
→ The cdpscripttest guide ·
Use it from your module ·
Agentic workflows ·
Testing this repository
I want to…
| Goal | Start here |
|---|---|
| Install the tools and see one work | Quickstart |
| Learn the idioms by building something small | Tutorial: your first script |
| Understand how these tools fit together | How cdp works |
| Record network traffic, including behind a login | Capture network traffic |
| Find what changed between two page loads | Differential capture |
| Automate a browser task repeatably | cdpscript |
| Let an AI agent drive the browser | Use cdp as an MCP server |
| Debug an Electron application | Electron debugging |
| Fetch through a proxy | churl behind a proxy |
| Fix something that is going wrong | Troubleshooting |
| Work on this repository | Testing |
| Look up a flag or command | Command reference |
| Read about one tool end to end | cdp · cdpscript · cdpscripttest · churl |
The other commands
Focused tools alongside the three entry points above. (native-host also
ships, but Chrome starts it — see Command reference.)
| Command | Use it for |
|---|---|
chrome-to-har |
One-shot HAR capture, plus differential capture |
churl |
Fetching a URL with JavaScript executed |
chdb |
Debugging a page: breakpoints, DOM, heap, tracing |
ndp |
Debugging Node.js and V8 |
chdb and ndp have no guide here: they are documented by their own --help
and go doc, and no page on this site has verified their workflows. Start with
chdb help or ndp help.
Every command documents its own flags, checked by a test that fails when a flag is added without being documented:
go doc ./cmd/cdp
See Command reference for the full list.
Next steps
- Quickstart — install and see a tool work.
- Tutorial: your first script — the guided build, once the quickstart runs.
- How cdp works — the model behind the tools, and what is stable.
- Troubleshooting — when a command misbehaves.
Already installed and looking for a specific task? Pick a row from the table above.