Browser Runtime

Webcmd uses a browser runtime for both interactive recording and generated workflow execution. The CLI session commands talk to an active runtime; exported workflows create or receive one through createWorkflowRuntime().

Opening sessions

webcmd open "https://example.com" --session default
webcmd open "https://example.com" --session demo --headed
webcmd open "https://example.com" --session dry-run --no-record

webcmd open prints the current URL to stdout, writes status to stderr, starts a control server, and stays alive until the session closes. Recording is enabled unless --no-record is passed.

Supported providers

webcmd open "https://example.com" --browser cloak
webcmd open "https://example.com" --browser chromium
webcmd open "https://example.com" --browser firefox
webcmd open "https://example.com" --browser webkit
webcmd open "https://example.com" --browser chromium --channel chrome
webcmd open "https://example.com" --browser camofox --camofox-url http://localhost:3000

Run npm run browsers:install in the package repo before using stock Playwright browsers if they are not installed. --channel is only supported with --browser chromium. Camofox requires --camofox-url and rejects auth, --profile, --user-data-dir, and --channel because the remote provider owns its own browser context.

Driving a session

Selectors are deliberately explicit. A click/fill target must include at least one durable selector, and --role requires --name.

webcmd snapshot --session demo
webcmd goto "https://example.com/settings" --session demo
webcmd click --session demo --role button --name "Save"
webcmd fill "aditya@example.com" --session demo --label "Email"
webcmd press Enter --session demo
webcmd wait url_contains "/settings" --session demo --timeout-ms 5000
webcmd close --session demo

Target selector options are --role, --name, --label, --placeholder, --test-id, --text, --css, --xpath, and repeated --selector <candidate...>.

Profiles and auth

Named profiles live under .webcmd/profiles/<name>:

webcmd open "https://accounts.google.com" \
  --session login \
  --headed \
  --profile default \
  --browser chromium \
  --channel chrome

You can also pass an absolute dedicated profile directory:

webcmd open "https://accounts.google.com" \
  --session google \
  --headed \
  --user-data-dir C:\webcmd-profiles\google \
  --browser chromium \
  --channel chrome

Avoid pointing --user-data-dir at your everyday Chrome profile while Chrome is open. Use a dedicated directory or Webcmd profile.

Auth commands

webcmd auth doctor <app-id> --profile default
webcmd auth login <app-id> --profile default --browser chromium --channel chrome
webcmd auth bind <app-id> --session login

auth doctor validates the profile against graph auth contracts. auth login opens a headed flow and polls until validation passes. auth bind validates auth state from an existing Webcmd session and records which profile or user-data-dir that session represents.

Generated workflow runtime

Generated workflow scripts should initialize like this:

import { createWorkflowRuntime, parseWorkflowArgs } from "webcmd/runtime";

export const workflow = {
  version: 1,
  id: "example",
  task: "Example task",
  params: {}
};

export async function run(input = {}, options = {}) {
  const runtime = await createWorkflowRuntime(options);
  try {
    await runtime.goto("https://example.com");
    return await runtime.snapshot();
  } finally {
    await runtime.close();
  }
}

For capabilities requiring browser identity, call createWorkflowRuntime({ ...options, auth: true }). auth: true defaults to .webcmd/profiles/default; callers can override with profile or userDataDir.