browsectl
CRITICAL: Before doing anything, run
browsectl setupto detect installed browsers and auto-download the matching WebDriver binary. Sessions persist to.browsectl/sessions.jsonacross CLI invocations — you do not need to create a new session every time.
WebDriver automation CLI for AI-driven browser control. browsectl provides subcommands for browser session management, tab control, element interaction, screenshots, batch execution, and an interactive REPL.
Installation
npm install -g @yorelog/browsectl
browsectl setup
Skills
Session & Driver Lifecycle
Session & driver lifecycle management.
| Command | Description |
|---|---|
setup | Detect browsers and download WebDriver binary |
status | Show driver and session status |
driver-start | Start the WebDriver server |
session-create | Create a new browser session |
session-list | List all active sessions |
session-use | Switch the default session |
session-delete | Delete a session |
Browser Commands
Browser interaction commands — navigate, click, type, screenshot, scroll, read state, wait.
| Command | Description |
|---|---|
run --type open | Navigate to a URL |
run --type click | Click a DOM element by CSS selector |
run --type fill | Type text into an input field character by character |
run --type paste | Paste text via clipboard simulation |
run --type screenshot | Capture a DOM element to PNG |
run --type scroll | Scroll the page or a specific element |
run --type title | Get the current page title |
run --type last-message-content | Extract the last message block (chat UIs) |
run --type wait | Wait for a condition (visible, hidden, URL, title, JS) |
Tab Management
Tab management — list, create, switch, and close browser tabs.
| Command | Description |
|---|---|
tab-list | List all open tabs |
tab-create | Open a new tab |
tab-switch | Switch to a tab by index, alias, or handle |
tab-close | Close a tab |
Batch Execution
Batch execution — run single commands, sequential batches from JSON files, and parallel groups.
| Command | Description |
|---|---|
run | Execute a single WebDriver command |
batch | Run a sequence of commands from a JSON file |
Selector Syntax
CSS selectors with ::text(/regex/flags) extension for filtering elements by text content.
Interactive REPL
Interactive REPL — live command entry, tab-completion, persistent history.
| Command | Description |
|---|---|
repl | Start the interactive REPL |
Global CLI Flags
| Flag | Default | Description |
|---|---|---|
--browser | chrome | Browser to automate: chrome or edge |
--server | http://127.0.0.1:9515 | WebDriver server URL |
--chromedriver | (auto-detected) | Path to WebDriver binary (chromedriver / msedgedriver) |
--chrome-binary | (auto-detected) | Path to browser binary |
--user-data-dir | ~/.browsectl/<browser>-profile | Browser user-data directory |
--profile-directory | Default | Browser profile directory name |
--headless | false | Run browser in headless mode |
--viewport | 1024,768 | Viewport size as width,height |
--session | (default session) | Session ID to operate on |
Platform Support
| OS | x64 | arm64 |
|---|---|---|
| macOS | ✅ | ✅ |
| Linux | ✅ | ✅ |
| Windows | ✅ | ✅ |