Browser automation for web testing, form filling, screenshots, and data extraction via CLI

GitHub stars
419

Install

/plugin install webctl@webctl

Run it inside Claude Code after adding the marketplace with /plugin marketplace add cosinusalpha/webctl.

Contents

Discovered from source

Skills 1

webctl - Browser Automation CLI

Setup

If webctl is not installed, run: pip install webctl && webctl setup

Workflow

# 1. Navigate — returns structured data + page summary
webctl navigate "https://example.com"

# 2. Interact using @refs or text descriptions
webctl click @e3
webctl type "Email" "user@example.com"

# 3. End session
webctl stop

Choosing the Right Approach

GoalCommand
Browse / interact with a pagenavigate URL — returns structured data + page summary (add --snapshot for full a11y with @refs)
Read article contentnavigate URL --read — returns readable markdown
Search a websitenavigate URL --search "query" — types query + returns results
Filter specific elementsnavigate URL --grep "€|price" — filtered a11y snapshot

Commands (10 total)

navigate - Go to URL

webctl navigate "https://example.com"                        # structured data + page summary (default)
webctl navigate "https://example.com" --snapshot              # full a11y snapshot with @refs
webctl navigate "https://example.com" --grep "€|price"       # filtered a11y snapshot
webctl navigate "https://example.com" --read                  # readable text content
webctl navigate "https://duckduckgo.com" --search "query"     # search + results snapshot

The default returns structured data (JSON-LD, Open Graph — price, rating, etc.) plus a page summary. Add --snapshot for the full a11y snapshot with @refs for interaction.

snapshot - Re-scan current page

webctl snapshot                     # all elements with @refs (default)
webctl snapshot --interactive-only  # just buttons/links/inputs
webctl snapshot --read              # readable text content
webctl snapshot --count             # just counts (zero context)
webctl snapshot --grep "pattern"    # filter by regex
webctl snapshot --within "role=main"  # scope to container

click - Click an element

webctl click @e3                    # by @ref (fastest)
webctl click "Submit"               # by text description
webctl click 'role=button name~="Submit"'  # by query (fallback)
webctl click "Submit" --snapshot    # click + return new page state
webctl click "Next" --snapshot --grep "result"  # click + filtered snapshot

type - Type text (auto-detects dropdowns and checkboxes)

webctl type @e2 "user@example.com"  # by @ref
webctl type "Email" "user@test.com" # by text description
webctl type "Country" "Germany"     # auto-selects from dropdown
webctl type "Search" "query" --submit  # type + press Enter
webctl type "Email" "x" --snapshot  # type + return page state

do - Batch multiple actions in one call

webctl do '[["type","Email","user@test.com"],["type","Password","secret"],["click","Log in"]]' --snapshot

Actions: click, type, press, wait. Stops on first failure.

press - Keyboard key

webctl press Enter
webctl press Escape
webctl press Tab

wait - Wait for condition

webctl wait stable                                  # best for SPAs (DOM stabilization)
webctl wait network-idle                            # for traditional page loads (avoid for SPAs with WebSocket/SSE)
webctl wait 'exists:role=button name~="Continue"'
webctl wait 'url-contains:"/dashboard"'
webctl wait 'hidden:role=dialog'

save - Save session state

webctl save                  # save to current session profile
webctl save my-auth          # save as named profile (reusable with -s my-auth)

stop - Close everything

webctl stop                  # closes browser + daemon (default)
webctl stop --keep-daemon    # only close browser

start - Explicit session start (usually not needed)

webctl start                                  # visible browser
webctl start --mode unattended                # headless
webctl navigate URL --mode attended           # auto-start with visible browser

Target Syntax

Actions (click, type) accept three target formats:

FormatExampleWhen to use
@ref@e3After a snapshot (fastest, most reliable)
Text"Submit"When you know the element text
Query'role=button name~="Submit"'When text is ambiguous

@refs are assigned by snapshot and navigate --snapshot/--search/--grep. They reset on each snapshot.

Text descriptions are fuzzy-matched against interactive elements. webctl prefers the right role for the action (click prefers buttons/links, type prefers textboxes).

Query syntax is the fallback: role=X name~="Y" (use name~= for contains, name= for exact).

Automatic Fallbacks

These happen transparently — you don't need to handle them:

  • Cookie/popup auto-dismiss: Overlays are dismissed before actions
  • Scroll-to-find: If element not found, scrolls down and retries (2x)
  • Click retry on overlay: If click intercepted by overlay, dismisses and retries
  • Smart type: type on combobox auto-uses select_option; on checkbox auto-uses check/uncheck

Common Patterns

Price Lookup (e-commerce)

webctl navigate "https://amazon.de/dp/B09HM94VDS"
# Structured data (price, rating) + snapshot with @refs for details
webctl stop

Read Article

webctl navigate "https://spiegel.de" --read
# Returns structured data + readable markdown content
webctl stop

Search and Extract

webctl navigate "https://duckduckgo.com" --search "query"
# Returns search results with @refs
webctl stop

Login

webctl navigate "https://example.com/login"
webctl do '[["type","Email","user@example.com"],["type","Password","secret"],["click","Log in"]]' --snapshot
webctl wait 'url-contains:"/dashboard"'
webctl stop

Form with Dropdown

webctl navigate "https://example.com/form"
webctl do '[["type","Name","John"],["type","Email","john@test.com"],["type","Country","Germany"],["click","Submit"]]' --snapshot
webctl stop

Find Specific Data on Complex Pages

webctl navigate "https://example.com" --grep "€|price|shipping"
# Returns only elements matching the pattern, with @refs
webctl stop

Human-In-The-Loop

For CAPTCHA, MFA, or manual steps (requires visible browser — don't use --mode unattended):

webctl start                                          # visible browser
webctl navigate "https://example.com/login"
webctl type "Email" "user@example.com" --submit
webctl prompt-secret --prompt "Enter MFA code:"       # pauses for human
webctl wait 'url-contains:"/dashboard"'
webctl stop

Sponsors

Details

Marketplace
cosinusalpha/webctl
Category
Development