wavexis 2.20.0

Browser automation CLI — wraps cdpwave and bidiwave

Browser automation CLI — wraps cdpwave and bidiwave. No Node.js, no Chromium download. Uses your existing Chrome/Edge. 170+ top-level CLI commands, 480+ sub-commands, 700+ backend methods.

Why wavexis?

wavexis is a command-line tool for browser automation. It wraps the cdpwave (Chrome DevTools Protocol) and bidiwave (WebDriver BiDi) libraries, exposing their capabilities through a single unified CLI. You don't need Node.js, Playwright, or a separate Chromium download — wavexis launches your existing Chrome or Edge installation directly.

Core concepts

• Backend — The browser driver that executes commands. wavexis supports two backends: CDP (default, via cdpwave) and BiDi (via bidiwave). Both expose the same public API over 60 CDP domains and 12 BiDi modules. On Chrome, the BiDi backend covers the full surface via the CDP bridge; on Firefox, only native BiDi methods are available.
• Action — A single operation (screenshot, eval, click, etc.). Each action maps to a CLI command or a step in a multi-action YAML config.
• Multi-action — A YAML config that chains multiple actions in sequence on a single browser session. Avoids the overhead of launching a browser per action.
• Serve mode — An HTTP API server that exposes all wavexis commands as REST endpoints with WebSocket streaming for real-time events.

Requirements

• Python 3.11 or higher
• A Chromium-based browser (Chrome, Edge, Brave, or Chromium) already installed
• No Node.js, no separate Chromium download

Install

# CDP backend (default, recommended)
pip install wavexis[cdp]

# BiDi backend
pip install wavexis[bidi]

# Serve mode + image extras
pip install wavexis[cdp,serve,image]

Docker

Serve mode in a container with Chromium pre-installed:

docker run -p 8080:8080 ghcr.io/mathiaspaulenko/wavexis:latest

curl -X POST http://localhost:8080/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  -o screenshot.png

Build locally:

docker build -t wavexis .
docker run -p 8080:8080 wavexis

Quick start

# Take a screenshot
wavexis screenshot https://example.com -o out.png

# Full-page screenshot
wavexis screenshot https://example.com -o full.png --full-page

# Screenshot of a specific element
wavexis screenshot https://example.com -o el.png --selector "h1"

# Generate a PDF
wavexis pdf https://example.com -o out.pdf --paper a4

# Evaluate JavaScript
wavexis eval https://example.com -e "document.title"

# Scrape page content
wavexis scrape https://example.com --selector "article"

# Emulate a device
wavexis emulation device https://example.com --device iphone-15 -o shot.png

REPL

Interactive REPL for live browser sessions. Launch a non-headless browser and execute commands in real time:

wavexis repl

Inside the REPL:

wavexis> navigate https://example.com
wavexis> screenshot
wavexis> eval document.title
wavexis> click #login-button
wavexis> type #username admin@example.com
wavexis> cookies
wavexis> url
wavexis> title
wavexis> wait #dashboard
wavexis> back
wavexis> help
wavexis> exit

Supported commands: navigate, screenshot, eval, click, type, fill, hover, key, cookies, url, title, wait <selector>, back, forward, reload, help, exit/quit.

Init wizard

Generate a wavexis.yaml config interactively from predefined templates:

wavexis init

Or generate directly with flags:

wavexis init -t multi-step -u https://example.com -s "#login" --text "admin" -o config.yaml

List available templates:

wavexis init --list

Templates: screenshot, pdf, scrape, eval, multi-step, cookies, har.

CI assertions

Use --assert with eval to create CI gates that pass or fail based on the result:

# Equality check — exit 0 if title matches, 1 otherwise
wavexis eval https://example.com -e "document.title" --assert "== Expected Title"

# Inequality
wavexis eval https://example.com -e "document.title" --assert "!= Old Title"

# Substring
wavexis eval https://example.com -e "document.body.innerText" --assert "contains Welcome"

# Regex
wavexis eval https://example.com -e "document.title" --assert "matches Error \\d+"

Output includes assert:, result:, and status: PASS/FAIL. Exit code 0 on pass, 1 on fail.

Stealth mode

Enable anti-bot stealth mode to hide headless browser indicators. Useful for scraping protected sites:

# Global flag — applies to all commands
wavexis --stealth screenshot https://example.com -o out.png
wavexis --stealth scrape https://protected-site.com --selector "article"

Stealth mode hides navigator.webdriver, fakes plugins, languages, chrome runtime, WebGL vendor/renderer, permissions API, navigator.connection, hardwareConcurrency, deviceMemory, and platform. Works with both CDP and BiDi backends.

Action caching

Cache action results to avoid re-analyzing pages when running multi-action workflows repeatedly:

# Cache results for 60 seconds
wavexis multi actions.yml --cache-ttl 60

Cacheable actions: screenshot, dom, scrape, eval, cookies, headers. Cache is keyed by URL, action type, and params hash.

WebExtension management

Install, uninstall, and list browser extensions:

# Install an unpacked extension directory
wavexis extension-install /path/to/extension/

# Install a .crx file
wavexis extension-install /path/to/extension.crx

# List installed extensions
wavexis extension-list

# Uninstall by extension ID
wavexis extension-uninstall <extension-id>

Browser preferences

Get and set browser preferences programmatically:

# Get a preference
wavexis pref-get download.default_directory

# Set a preference
wavexis pref-set download.default_directory /tmp/downloads

Performance metrics

Capture Core Web Vitals and performance data:

# Key metrics (LCP, FCP, CLS, TTFB) with human-readable summary
wavexis perf metrics https://example.com

# CPU trace
wavexis perf trace https://example.com --duration 5000 -o trace.json

# CPU profile
wavexis perf profile https://example.com -o profile.json

# JS code coverage
wavexis perf coverage https://example.com -o coverage.json

# CSS coverage
wavexis perf css-coverage https://example.com -o css-coverage.json

# Heap snapshot
wavexis perf heap https://example.com -o heap.json

Sub-commands: metrics, trace, profile, heap, coverage, css-coverage. wavexis perf --url <url> is a shortcut for perf metrics.

Core Web Vitals scoring

Measure LCP, CLS, INP with actionable ratings and a 0-100 score:

# Basic measurement
wavexis cwv https://example.com

# With CI budgets (fails if thresholds exceeded)
wavexis cwv https://example.com --budget '{"lcp_ms":2500,"cls":0.1,"inp_ms":200}'

# Save report to file
wavexis cwv https://example.com -o cwv-report.json

Ratings: good / needs-improvement / poor based on official Google thresholds.

Request modification

Intercept and modify network requests and responses in-flight:

# Modify request headers for matching URLs
wavexis modify https://example.com -p "*/api/*" --header "X-Custom: value"

# Modify response body
wavexis modify-response https://example.com -p "*/api/*" -b '{"modified":true}' -s 200

# Keep browser open for interception
wavexis modify https://example.com -p "*/api/*" --wait 10

Auth

Apply an auth context (cookies, headers, basic auth) from a JSON file and navigate to a URL:

# Apply auth context and print page title
wavexis auth context.json https://example.com/login

# Apply auth context and save a screenshot
wavexis auth context.json https://example.com/login --screenshot -o authed.png

The auth context JSON file supports cookies, headers, username, and password fields. See wavexis auth --help for details.

Record & Replay

Record a browsing session to YAML and replay it later:

# Generate a YAML session from action types (non-interactive)
wavexis record https://example.com -o session.yml --actions "screenshot,eval"

# Record real interactions in a visible browser window
wavexis record https://example.com --interactive --duration 60 -o session.yml

# Replay a recorded session
wavexis replay session.yml

Serve mode

HTTP API server powered by aiohttp with WebSocket streaming:

wavexis serve --host 0.0.0.0 --port 8080

# With rate limiting (60 requests/min)
wavexis serve --host 0.0.0.0 --port 8080 --rate-limit 60

curl -X POST http://localhost:8080/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  -o screenshot.png

WebSocket endpoint at /ws for real-time streaming of screenshots, console events, navigation, DOM mutations, and performance metrics:

import aiohttp, json, asyncio

async def stream():
    async with aiohttp.ClientSession() as s:
        async with s.ws_connect("ws://localhost:8080/ws") as ws:
            await ws.send_json({"url": "https://example.com", "events": ["screenshot"], "interval": 2.0})
            async for msg in ws:
                data = json.loads(msg.data)
                if data["type"] == "screenshot":
                    print(f"Got frame ({len(data['data'])} bytes)")

asyncio.run(stream())

Multi-action

Create a YAML config and run multiple actions in sequence on a single browser session:

# actions.yml
actions:
  - screenshot:
      url: https://example.com
      full_page: true
  - eval:
      url: https://example.com
      expression: document.title
  - pdf:
      url: https://example.com
      paper: a4

wavexis multi actions.yml

Watch mode

Re-execute the config automatically when the file changes. Useful for iterative config development:

wavexis multi actions.yml --watch

Dry run

Validate the config and show the planned actions without launching a browser:

wavexis multi actions.yml --dry-run

Supported action types

Cookies and headers in multi

actions:
  - cookies:
      url: https://example.com
      action: get
  - headers:
      url: https://example.com
      action: set-headers
      headers:
        X-Custom-Header: my-value
  - screenshot:
      url: https://example.com

Backends

wavexis supports two backends with feature parity on Chrome:

• CDP (cdpwave) — default, Chrome DevTools Protocol. pip install wavexis[cdp]
• BiDi (bidiwave) — WebDriver BiDi protocol, uses BiDi native + JS workarounds + CDP bridge (Chrome only). pip install wavexis[bidi]

Select with --backend:

wavexis --backend bidi screenshot https://example.com -o out.png

Graceful backend degradation

If the preferred backend fails to initialize (e.g. dependency not installed), wavexis automatically falls back to the next available backend:

# Prefers CDP, falls back to BiDi if cdpwave is not installed
wavexis screenshot https://example.com -o out.png

# Prefers BiDi, falls back to CDP if bidiwave is not installed
wavexis --backend bidi screenshot https://example.com -o out.png

Feature parity

Both backends expose the same public API across 60 CDP domains and 12 BiDi modules. BiDi uses native BiDi commands, JS workarounds (script.evaluate), or the CDP bridge (browser.cdp.sendCommand) when needed. The CDP bridge requires Chrome — on Firefox only native BiDi methods are available, so methods marked "CDP bridge" below are Chrome-only.

Commands

wavexis provides 170+ top-level CLI commands plus 480+ sub-commands organized into categories:

Run wavexis --help for the full list.

Comparison

Documentation

Full docs at mathiaspaulenko.github.io/wavexis.

Contributing

See CONTRIBUTING.md for development setup, testing, and release guidelines.

Security

To report a security vulnerability, see SECURITY.md.

License

MIT