BrowseCTL

WebDriver automation CLI for AI-driven browser control. Provides session management, tab control, element interaction, screenshots, batch execution, and an interactive REPL.

CRITICAL: Before doing anything, run browsectl setup to detect installed browsers and auto-download the matching WebDriver binary. Sessions persist to .browsectl/sessions.json across 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

skills/session.md

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

skills/browser.md

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

skills/tabs.md

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

skills/batch.md

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

skills/selectors.md

CSS selectors with ::text(/regex/flags) extension for filtering elements by text content.

Interactive REPL

skills/repl.md

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	✅	✅