nicobailon/surf-cli
Overview
This skill exposes a battle-tested CLI to control Chrome for testing, automation, and debugging. It provides zero-config browser control for navigating pages, interacting with elements, taking screenshots, inspecting network/console, emulating devices, and issuing AI queries using logged-in browser sessions. The CLI is agent-agnostic and designed for fast, repeatable automation across development and QA workflows.
How this skill works
Commands talk to a running Chrome instance via CLI or Unix socket and use DevTools to drive navigation, input, screenshots, and network inspection. It reads page structure into element refs, supports semantic locating (role/label/text), and streams DevTools events for real-time debugging. AI queries run through the browser session so no API keys are required, provided you are logged into the target service in Chrome.
When to use it
- Automating form fills, login flows, and repetitive UI tasks from scripts or CI
- Capturing screenshots, full-page snapshots, or element-level images for visual tests
- Inspecting network requests, console logs, and performance traces during debugging
- Emulating devices, network/CPU conditions, geolocation, or touch input for QA
- Running agent workflows that need controlled, isolated browser windows or tabs
- Querying ChatGPT/Gemini/Perplexity/Grok via a logged-in Chrome session without API keys
Best practices
- Call page.read first to generate stable element refs before interacting
- Prefer semantic locate (role/label/text) over brittle selectors when possible
- Use window isolation to create per-agent contexts and avoid cross-contamination
- Validate AI UI bindings (e.g., surf grok --validate) when model selection fails
- Record network or perf traces for intermittent issues and increase timeouts for slow models
Example use cases
- Run a named workflow to log into an app, exercise features, and snapshot results for CI
- Automate a multi-field form submission using form.fill or locate.label commands
- Stream network events while reproducing a bug to capture failing requests and response bodies
- Throttling network and CPU to test app behavior on slow mobile conditions
- Ask Gemini or ChatGPT to summarize the current page context using --with-page for richer AI responses
FAQ
No. AI queries use the browser's logged-in session; you must be signed into the service in Chrome.
How do I handle UI changes that break commands?
Run validation (e.g., surf grok --validate) to inspect UI selectors, update local settings, or use semantic locate to target accessible roles and labels.
Can I run workflows in CI?
Yes. Workflows support dry-run validation, named JSON workflows, and can run headless or in isolated windows depending on environment setup.
2 skills
This skill lets you automate and inspect Chrome tasks from the CLI, enabling reliable browser testing, debugging, and AI-assisted workflows.
This skill helps you navigate and modify the surf-cli codebase, enabling browser automation, CDP access, and AI agent orchestration.
