browsectl#

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#

sh

npm install -g @yorelog/browsectl
browsectl setup

Skills#

Session & Driver Lifecycle#

skills/session.md

Session & driver lifecycle management.

CommandDescriptionsetupDetect browsers and download WebDriver binarystatusShow driver and session statusdriver-startStart the WebDriver serversession-createCreate a new browser sessionsession-listList all active sessionssession-useSwitch the default sessionsession-deleteDelete a session

Browser Commands#

skills/browser.md

Browser interaction commands — navigate, click, type, screenshot, scroll, read state, wait.

CommandDescriptionrun --type openNavigate to a URLrun --type clickClick a DOM element by CSS selectorrun --type fillType text into an input field character by characterrun --type pastePaste text via clipboard simulationrun --type screenshotCapture a DOM element to PNGrun --type scrollScroll the page or a specific elementrun --type titleGet the current page titlerun --type last-message-contentExtract the last message block (chat UIs)run --type waitWait for a condition (visible, hidden, URL, title, JS)

Tab Management#

skills/tabs.md

Tab management — list, create, switch, and close browser tabs.

CommandDescriptiontab-listList all open tabstab-createOpen a new tabtab-switchSwitch to a tab by index, alias, or handletab-closeClose a tab

Batch Execution#

skills/batch.md

Batch execution — run single commands, sequential batches from JSON files, and parallel groups.

CommandDescriptionrunExecute a single WebDriver commandbatchRun 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.

CommandDescriptionreplStart the interactive REPL

Global CLI Flags#

FlagDefaultDescription--browser``chromeBrowser to automate: chrome or edge``--server``http://127.0.0.1:9515WebDriver server URL--chromedriver_(auto-detected)Path to WebDriver binary (chromedriver / msedgedriver)--chrome-binary(auto-detected)Path to browser binary--user-data-dir``~/.browsectl/<browser>-profileBrowser user-data directory--profile-directory``DefaultBrowser profile directory name--headless``falseRun browser in headless mode--viewport``1024,768Viewport size as width,height``--session(default session)_Session ID to operate on

Platform Support#

OSx64arm64macOS✅✅Linux✅✅Windows✅✅