> ## Documentation Index > Fetch the complete documentation index at: https://webcmd.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Command Surface > The Webcmd commands agents use for discovery, adapter execution, plugins, profiles, and validation. # Command Surface Most people should start with the [Prompt Cookbook](/docs/agent-prompts) and let an agent use these commands. This page is the detailed surface for debugging, authoring, and advanced manual use. ## Discovery ```bash theme={null} webcmd list webcmd list -f json webcmd list --tag search -f json webcmd --help webcmd --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 -f json` to filter commands by an exact, case-insensitive tag before rendering. For search-capable commands, use `--tag search`. ## Adapter Execution ```bash theme={null} webcmd [args] [options] ``` Examples: ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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 ` only when intentionally routing an adapter into an explicit session. Raw browser commands must always pass it. The retired positional session form is invalid: ```bash theme={null} 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 ` 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 ```bash theme={null} 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`: ```bash theme={null} 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: ```bash theme={null} 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 ` | 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. ```bash theme={null} # Local: existing local profile management webcmd profile list webcmd profile rename 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 ` values lazily create separate local state; local `list`, `rename`, and `use` are unchanged. In hosted mode, `--profile ` 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: ```text theme={null} 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`: ```bash theme={null} webcmd plugin search ycombinator -f json webcmd plugin install ``` 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. ```bash theme={null} 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 ` and `--provider ` to skip the prompts, or `--path ` 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: ```text theme={null} 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.