wdiox — WebdriverIO Execute

Interactive browser and app CLI for developers, powered by WebdriverIO.

npm install -g webdriverio-execute

How it works

Each command is stateless. Sessions are stored as JSON in .wdiox/ in the current working directory (add .wdiox/ to your .gitignore). Commands attach to an existing session by reading that file — no daemon, no background process.

snapshot captures all interactable elements and assigns short refs (e1, e2, …). Subsequent commands use those refs to act on elements.

Every action command appends a step to <session>.steps.json. On close, the steps file is renamed to <session>-<YYYYMMDDHHmmss>.steps.json and preserved on disk.

Commands

open / new / start

Open a browser or Appium session.

wdiox open https://example.com
wdiox open https://example.com --browser firefox
wdiox open https://example.com --headless
wdiox open https://internetbank.example.com --no-web-security   # bypass CSP
wdiox open --app /path/to/app.apk --device "emulator-5554"
wdiox open --app /path/to/app.ipa --device "iPhone 15"

# Attach to an already-running Chrome instance (via CDP)
wdiox open --attach
wdiox open --attach --debug-port 9333 --debug-host 127.0.0.1

# Attach to an already-running mobile app (Appium)
wdiox open --attach --device "emulator-5554" --platform android

# Reuse an existing WebdriverIO config (full capabilities override)
wdiox open --config wdio.conf.ts

| Option | Default | Description | |---|---|---| | --browser | chrome | Browser to use (chrome, firefox, edge, safari) | | --headless | false | Run Chrome in headless mode | | --no-web-security | — | Disable Chrome web security and CSP (use when snapshot fails on strict-CSP sites) | | --config | — | Path to wdio.conf.js or wdio.conf.ts — fully overrides browser/Appium capabilities | | --app | — | Path to mobile app (.apk, .ipa, .app) | | --device | emulator-5554 | Device name | | --platform | auto-detected | android or ios | | --hostname | localhost | WebDriver/Appium server hostname | | --port | 4723 (mobile) / 4444 (browser) | Server port | | --grant-permissions | true | Auto-grant app permissions (Appium) | | --accept-alert | true | Auto-accept native alerts (Appium) | | --auto-dismiss | false | Auto-dismiss native alerts (Appium) | | --attach | false | Attach to an already-running browser or app instead of launching a new one | | --debug-port | 9222 | Chrome remote debugging port (used with --attach) | | --debug-host | localhost | Chrome remote debugging host (used with --attach) | | --session | default | Session name |

If a session with the given name is already active, you'll be prompted to close it first.

snapshot

Capture interactable elements on the current page or screen and assign numbered refs.

wdiox snapshot
wdiox snapshot --no-visible   # include off-screen elements

 Page: https://example.com/login

e1    input[email]  "Email address"  #email
e2    input[password]  "Password"  #password
e3    button  "Sign in"  button*=Sign in

 3 elements - default session

click

Click an element by ref.

wdiox click e3

fill / type

Clear and type into an input by ref.

wdiox fill e1 "[email protected]"
wdiox type e2 "mysecretpassword"

screenshot

Save a screenshot.

wdiox screenshot
wdiox screenshot /tmp/login-page.png

navigate / goto

Navigate to a URL, or control browser history.

wdiox navigate https://example.com/login
wdiox goto https://example.com/login

wdiox navigate refresh   # reload current page
wdiox navigate back      # go back in history
wdiox navigate forward   # go forward in history

scroll / swipe

Scroll the page (browser) or swipe (mobile).

wdiox scroll down
wdiox scroll up --pixels 1000
wdiox swipe left --duration 300 --percent 0.9

| Option | Default | Description | |---|---|---| | --pixels | 500 | Pixels to scroll (browser only) | | --duration | 500 | Swipe duration in ms (mobile only) | | --percent | 0.5 (vertical) / 0.95 (horizontal) | Screen percentage to swipe, 0–1 (mobile only) |

Browser: up/down only. For horizontal scroll use execute.

execute

Execute JavaScript in the browser, or run a mobile command via Appium.

wdiox execute "return document.title"
wdiox execute "return arguments[0].textContent" --args '["#main"]'
wdiox execute "mobile: pressKey" --args '{"keycode": 4}'

| Option | Default | Description | |---|---|---| | --args | — | JSON-encoded arguments (array or single value) |

String args that match a valid CSS selector are automatically resolved to DOM elements before the script runs.

steps / record

Display recorded steps for the active session or list archived step files.

wdiox steps                       # active session steps
wdiox steps --json                # raw JSON output
wdiox steps --list                # list all archived step files
wdiox steps --file .wdiox/<session>-20240101120000.steps.json

| Option | Default | Description | |---|---|---| | --json | false | Output raw JSON | | --list | false | List all archived steps files | | --file | — | Display a specific archived steps file by path |

skills

Progressive documentation for AI agents and explorers. Lists all topics or loads a specific guide on demand.

wdiox skills                    # list all topics
wdiox skills open               # full guide for the open command
wdiox skills execute            # JavaScript & mobile command guide
wdiox skills open --flags       # flags reference only

close / stop

Close the current session.

wdiox close
wdiox close --session myapp

ls / session-list

List all active sessions.

wdiox ls

NAME     BROWSER   URL                       STATUS
default  chrome    https://example.com       active
myapp    Android   /path/to/app.apk          active

Multi-session

Every command accepts --session <name> (or -s <name>) to target a specific session. The WDIO_SESSION environment variable sets the default session name.

wdiox open https://site-a.com --session a
wdiox open https://site-b.com --session b
wdiox snapshot --session a
wdiox click e1 --session a
wdiox close --session b

Typical browser workflow

wdiox open https://example.com
wdiox snapshot
wdiox fill e1 "[email protected]"
wdiox fill e2 "password"
wdiox click e3
wdiox navigate https://example.com/dashboard
wdiox scroll down
wdiox screenshot
wdiox steps
wdiox close

Typical mobile workflow

wdiox open --app ./app.apk --device "emulator-5554"
wdiox snapshot
wdiox click e1
wdiox fill e2 "hello"
wdiox close