Command Surface

Most people should start with the Prompt Cookbook and let an agent use these commands. This page is the detailed surface for debugging, authoring, and advanced manual use.

Discovery

webcmd list
webcmd list -f json
webcmd list --tag search -f json
webcmd <site> --help
webcmd <site> <command> --help

webcmd list -f json is the source of truth for agents. It includes the site, command name, args, output columns, strategy, browser requirement, tags, and keywords. Use webcmd list --tag <tag> -f json to filter commands by an exact, case-insensitive tag before rendering. For search-capable commands, use --tag search.

Adapter Execution

webcmd <site> <command> [args] [options]

Examples:

webcmd hackernews top --limit 10
webcmd wikipedia summary "Command-line interface"
webcmd pubmed search "agentic browser automation" --limit 5 -f json

Agents should prefer existing adapters before raw browser exploration. For search and fetch tasks, use the bundled smart-search skill: it tries fetch-based search first, explicit browser Sessions after eligible fetch failures, and search adapters last.

Search and Fetch

Use webcmd web fetch for direct URL fetches and fetch-first web search. It is built into the CLI, so it works on a fresh install with no plugins.

webcmd web fetch --url https://example.com/article
webcmd web fetch --url "https://duckduckgo.com/html/?q=agentic%20browser%20automation"
webcmd web fetch --url "https://www.bing.com/search?q=agentic%20browser%20automation"

web fetch tries plain HTTP first, then browser-impersonating TLS clients. It remains local in both modes and never opens a browser. If a page requires browser rendering or blocks non-browser fetches, it returns FETCH_REQUIRES_BROWSER or FETCH_BLOCKED; only those codes permit explicit browser fallback. For either code, create one Session, navigate with browser run, inspect with a read snapshot, reuse the Session for allowed browser work, and close it:

webcmd --profile work session create
# Copy the returned full ID:
# session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45

webcmd --profile work \
  --session session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45 \
  browser run --stdin <<'JS'
await page.goto('https://example.com');
return { url: page.url(), title: await page.title() };
JS

webcmd --profile work \
  --session session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45 \
  browser snapshot --snapshot-mode read

webcmd --profile work session close \
  session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45

Local browser commands use Cloak. Hosted browser commands use Webcmd Cloud and Browser Use; web fetch still runs locally.

Browser Programs

Create an opaque session before raw browser work. Profiles hold cookie/auth state; sessions are browser workspaces within that profile. Adapter commands may omit --session and use their profile’s adapter-default session; pass --session <session-id> only when intentionally routing an adapter into an explicit session. Raw browser commands must always pass it. The retired positional session form is invalid:

webcmd session create -f json
webcmd --session session_abc browser snapshot --snapshot-mode act
webcmd --session session_abc browser snapshot --snapshot-mode read
webcmd --session session_abc browser run --stdin --timeout 45
webcmd --session session_abc browser run --stdin --no-snapshot-diff
webcmd session list
webcmd session close session_abc

session create, session list, and session close accept the universal output formats. An explicit -f table stays in table format when redirected, while an empty structured session list remains machine-readable (for example, [] with -f json). Agents sharing a profile can work in parallel by creating separate Sessions. An authentication handoff is scoped to the Session that started it: run the returned verification command verbatim because it includes --session when needed. session close is blocked while that Session has a live handoff. Use snapshot for explicit page inspection. act is the default action-first mode, tree preserves fuller page structure, and read extracts readable article/content text. Exactly one of --file <path> or --stdin is required for run. The CLI reads files locally and sends source—not the path—to the local daemon. --timeout is in seconds and --max-output bounds returned results and logs. Successful runs return a snapshotDiff by default; pass --no-snapshot-diff only when the program is pure read-only and its result already contains the needed state. The program runs in a fresh QuickJS sandbox with page, context, browser, and console globals. page.snapshotForAI() is not available. It can use the supported Page/Frame/Locator methods and passively inspect request and response events. It cannot access Node.js, the filesystem, environment variables, raw CDP endpoints, browser launch/connect APIs, browser-context ownership, or context.newPage(). Screenshot bytes are written to a Webcmd-owned cache directory and returned as a receipt. The public raw-browser surface is tabs, bind, run, and snapshot. Reusable adapters continue to use the existing IPage API. Playwright-style programs are for reconnaissance and ad-hoc multi-step work; they are not pasted into adapter modules.

Top-Level Commands

Command	Purpose
`list`	Show registered core, legacy user, plugin, and external commands.
`setup`	Choose local or hosted mode interactively.
`doctor`	Diagnose browser bridge and daemon connectivity.
`daemon`	Manage the local Webcmd daemon: status, stop, and restart.
`browser`	Agent-facing browser runtime for exploration and verification.
`web`	Local URL fetch helpers.
`profile`	List, rename, and select browser runtime profiles.
`auth`	Inspect website login status, and refresh logged-in site sessions.
`plugin`	Install, update, list, create, and uninstall plugins.
`adapter`	Inspect or remove legacy adapters in `~/.webcmd/clis/`.
`external`	Register or install external local CLIs.
`validate`	Validate adapter definitions.
`verify`	Validate and smoke test an adapter.
`convention-audit`	Scan adapters for agent-native convention violations.
`skills`	List, add, update, and remove bundled Webcmd agent skills.
`completion`	Print shell completion scripts.

Output Formats

webcmd hackernews top -f table
webcmd hackernews top -f plain
webcmd hackernews top -f json
webcmd hackernews top -f yaml
webcmd hackernews top -f md
webcmd hackernews top -f csv

plain prints key: value lines instead of a table, and prints the bare value when a command returns a single field named response, content, markdown, text, or value. It suits chat-style commands. yml and markdown are accepted aliases for yaml and md. Agents should use JSON unless they are presenting output to a human.

Reports and status commands

validate, verify, doctor, skills, adapter status, daemon status, and profile list also accept -f/--format:

webcmd validate -f json
webcmd verify -f yaml
webcmd doctor -f json
webcmd daemon status -f json
webcmd profile list -f json

Each keeps its human-readable report as the table rendering, which stays the default. Pass another format to get the underlying result object instead — the validation report for validate, the verify report for verify, the diagnostic report for doctor, and a row set for profile list. daemon status -f json returns { "running": false } when no daemon is reachable, and otherwise reports running, stale, pid, version, uptimeMs, runtimeConnected, profiles, memoryMB, and port. profile list returns one row per profile with contextId, alias, default, connected, and runtimeVersion, covering both connected profiles and saved aliases that are not currently connected. If the daemon is unreachable or stale, profile list -f json/-f yaml fails with a DAEMON_UNAVAILABLE error (exit 1) and a restart hint instead of returning [] — an empty list and an unreadable runtime are different facts.

Adapter verification reports

browser verify accepts -f/--format. Its default table rendering is the human progress report; any other format returns the verification result as data instead:

webcmd browser verify hn/top -f json

The report carries ok, site, command, rowCount, a fixture block (path, exists, action), and a memory block mirroring the site-memory check. Failures replace the prose with structured detail: shapeFailures for row-shape violations, matchFailures for fixture mismatches, and an error object with a code (ADAPTER_NOT_FOUND, ADAPTER_EXEC_FAILED, ADAPTER_OUTPUT_NOT_JSON) when the adapter could not be run or read. The exit code is unchanged in every case, so -f json is safe to add to an existing verification step.

Global Flags

Flag / Env	Purpose
`--workspace <id>`	Hosted mode only. Sets the ambient workspace for this invocation.
`WEBCMD_WORKSPACE`	Hosted mode only. Sets the ambient workspace when `--workspace` is not passed.

Workspace resolution precedence is --workspace flag, then WEBCMD_WORKSPACE env var, then an implicit default workspace. The CLI sends the resolved workspace as the X-Webcmd-Workspace header on hosted requests. Local mode has no workspace concept.

Profiles

Profiles keep login state separate. The profile surface depends on the selected mode.

# Local: existing local profile management
webcmd profile list
webcmd profile rename <context-id> work
webcmd profile use work

# Hosted: profile management within the ambient workspace
webcmd profile list
webcmd --workspace user_64256 profile list
webcmd profile delete profile_abc123

In local mode, arbitrary --profile <name> values lazily create separate local state; local list, rename, and use are unchanged. In hosted mode, --profile <name> selects a persona within the ambient workspace; an omitted selector or --profile default lazily creates that workspace’s default profile. Hosted list returns profile rows scoped to the ambient workspace; delete takes an immutable profile ID and returns { "ok": true, "deleted": true }, permanently removing that hosted browser state. Each profile row has id, name, workspace, default, status, createdAt, updatedAt, and lastUsedAt. status is pending or available. Cloud provider identifiers are never exposed. Prompt example:

Use the `work` profile for this Webcmd task. If it is not authenticated, stop and ask me to sign in.

Plugins

Local mode supports plugin install, update, list, create, uninstall, catalog, search, and related marketplace commands. The core package includes no site adapters. Search first, then explicitly use the returned installSource:

webcmd plugin search ycombinator -f json
webcmd plugin install <installSource-from-search>

Use direct plugin install github:... only when you already know the source. For missing or unknown sites, plugin search is the freshness boundary; it reads the current catalog instead of relying on package contents. Hosted mode supports plugin search, plugin install, plugin list, plugin uninstall, plugin update, and plugin create for Webcmd-verified marketplace adapters. Plugin catalog source management remains local-only. plugin list, plugin search, plugin catalog list, and plugin catalog add accept -f/--format. plugin list -f json returns an array (including [] when no plugins are installed); plugin catalog list -f json returns its catalog object. yml and markdown normalize to yaml and md, and unknown format names are usage errors.

Skills

Bundled agent skills ship with the package. webcmd skills add links them into an agent harness and is part of first-time setup.

webcmd skills list
webcmd skills add
webcmd skills update
webcmd skills remove

On a TTY, skills add prompts for whichever of scope and harness you did not pass. Use --scope <user|project> and --provider <agents|codex|claude> to skip the prompts, or --path <skills-dir> to link into a custom directory. Outside a TTY, and with --json, it never prompts. Run skills update after upgrading the package to refresh the links.

External CLIs

Agents can expose local tools through Webcmd, such as gh, docker, vercel, or internal CLIs. Prompt example:

Register our internal `releasectl` binary as a Webcmd external CLI with a short description and verify that `webcmd releasectl --help` works.

Useful Paths

Path	Purpose
`~/.webcmd/`	User-level Webcmd state.
`~/.webcmd/clis/`	Legacy private adapters retained for compatibility.
`~/.webcmd/cache/browser-network/`	Browser network capture cache.
`~/.webcmd/cache/browser-run/`	Host-owned browser-run screenshot artifacts.
`~/.webcmd/external-clis.yaml`	User external CLI registry.
`skills/`	Bundled agent skills shipped with the package.

These paths are mostly useful when reviewing an agent’s changes or packaging adapters into plugins.

Start

Agent Harnesses

Understand Webcmd

Build and Share

Use Cases

Reference and Support

Command Surface

Command Surface

Discovery

Adapter Execution

Search and Fetch

Browser Programs

Top-Level Commands

Output Formats

Reports and status commands

Adapter verification reports

Global Flags

Profiles

Plugins

Skills

External CLIs

Useful Paths

​Command Surface

​Discovery

​Adapter Execution

​Search and Fetch

​Browser Programs

​Top-Level Commands

​Output Formats

​Reports and status commands

​Adapter verification reports

​Global Flags

​Profiles

​Plugins

​Skills

​External CLIs

​Useful Paths

Command Surface

Discovery

Adapter Execution

Search and Fetch

Browser Programs

Top-Level Commands

Output Formats

Reports and status commands

Adapter verification reports

Global Flags

Profiles

Plugins

Skills

External CLIs

Useful Paths