CLI Reference

Setup

webcmd setup [--scope user|local] [--skills-root <path>]

Installs Webcmd skills globally (~/.agents/skills/) or locally (.agents/skills/). Use --skills-root to target a custom skills directory.

Browser sessions

webcmd open <url> [--session <id>] [--browser cloak|chromium|firefox|webkit|camofox]
  [--camofox-url <url>] [--profile <name>] [--user-data-dir <path>]
  [--channel <channel>] [--headed] [--no-record]

webcmd snapshot [--session <id>]
webcmd goto <url> [--session <id>]
webcmd click [--session <id>] <selector flags>
webcmd fill <value> [--session <id>] <selector flags>
webcmd press <key> [--session <id>]
webcmd wait url_matches|url_contains <value> [--session <id>] [--timeout-ms <ms>]
webcmd handoff [--session <id>]
webcmd resume [--session <id>]
webcmd close [--session <id>]
webcmd journal [--session <id>] [--compact]

Selector flags: --role, --name, --label, --placeholder, --test-id, --text, --css, --xpath, --selector <candidate...>. At least one selector is required; --role requires --name.

Network

webcmd network list [--session <id>] [--method <csv>] [--type <csv>]
webcmd network show <id> [--session <id>]
webcmd network summary [--session <id>]
webcmd network diff <before-event-id> <after-event-id> [--session <id>]
webcmd network mark <id> --mark important|ignore|side-effect [--session <id>]
webcmd network candidates [--session <id>] [--api-workflow]

Network records are redacted and stored in .webcmd/sessions/<session>/network.jsonl. Marks are stored separately in network.marks.json.

Auth

webcmd auth doctor <app-id> [--profile <name>] [--user-data-dir <path>]
  [--capability <id>] [--browser <provider>] [--channel <channel>]

webcmd auth login <app-id> [--profile <name>] [--user-data-dir <path>]
  [--capability <id>] [--browser <provider>] [--channel <channel>]
  [--start-url <url>] [--timeout-ms <ms>] [--poll-ms <ms>] [--headless]

webcmd auth bind <app-id> --session <id>
  [--capability <id>] [--profile <name>] [--user-data-dir <path>]

doctor validates a saved profile against graph auth contracts. login opens a browser and waits for validation. bind validates auth state from an existing active session.

Authoring packets

webcmd author cli --task <task> [--operation create|update|heal]
  [--app-id <id>] [--url <url>] [--target <path>]
  [--max-areas <n>] [--max-actions <n>] [--max-time-minutes <n>]
  [--max-mutating-samples <n>]

webcmd author workflow --task <task> [--operation create|update|heal]
  [--app-id <id>] [--url <url>] [--target <path>]
  [--max-areas <n>] [--max-actions <n>] [--max-time-minutes <n>]
  [--max-mutating-samples <n>]

Creates .webcmd/authoring/<target>-<artifact>-<operation>.packet.json. Default discovery budget is breadth-first for CLIs and depth-first for workflows.

Distillation

webcmd distill prepare --session <id> --sample-task <task> [--sample key=value ...]
webcmd distill apply <plan>

prepare writes .webcmd/sessions/<session>/distill.packet.json and network-candidates.json. apply writes or updates .webcmd/graphs/<app-id>/capabilities.json.

--sample values parse true, false, null, and numbers; everything else stays a string.

Workflows

webcmd workflow <app-id> --task <task>
webcmd workflow <app-id> --plan <plan.json>
webcmd workflow list
webcmd run <workflow>
webcmd run <domain>/<workflow>
webcmd run <workflow> --help

--task writes a workflow materialization packet. --plan writes .webcmd/exports/workflows/<domain>/<workflow-id>.mjs. run --help prints workflow inputs and outputs.

Generated CLIs

webcmd cli <app-id> --task <task> [--skills-root <path>]
webcmd cli <app-id> --plan <plan.json>
  [--export <target>] [--force] [--install-skill [path]]
  [--no-install-skill] [--skills-root <path>]

--task writes a CLI materialization packet. --plan writes .webcmd/exports/clis/<domain>/. --install-skill syncs the generated app skill into a skills directory; --force allows overwriting an existing installed app skill.

App registry

webcmd apps index <cli-dir> --app-id <id> --name <name>
  --base-url <url...> --binary <binary> --summary <summary>
  --read-before-acting <path...>

webcmd apps match <task> [--url <url>]

The registry lets agents find generated app CLIs that match a task or current URL.

Verification

webcmd verify <workflow.mjs|generated-cli-dir>

Verifies direct workflow scripts ending in .mjs or generated CLI directories. Workflow verification uses an injected fake runtime; generated CLI verification checks package structure and metadata.

Public package exports

import {
  version,
  appendJournalEvent,
  readJournalEvents,
  diffSnapshots,
  renderAppSkill,
  installAppSkillExport
} from "@agentrhq/webcmd";

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

Important paths

Common failures