> ## 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

> Browser, Session, Profile, setup, diagnostics, and output commands used by Webcmd agents.

# Command Surface

Most people should start with the [Prompt Cookbook](https://webcmd.dev/docs/agent-prompts.md) and let an
agent operate Webcmd. This page documents the public browser command surface
for debugging and advanced manual use.

## Sessions

Create a named Session before browser work. Its readable ID is immutable and
Profile-scoped, so keep using the same Profile and ID for the Session's lifetime.

```bash theme={null}
webcmd --profile work session create "Work Project" -f json
# id: work-project-k7
webcmd --profile work --session work-project-k7 browser tabs
webcmd --profile work session list -f json
webcmd --profile work session close work-project-k7
```

Agents sharing a Profile can work in parallel by creating separate Sessions.
An authentication handoff belongs to the Session that started it. Run the
returned verification command verbatim because it includes `--session` when
needed. `session close` is blocked while the Session has a live handoff.

`session create`, `session list`, and `session close` accept the universal
output formats. An explicit `-f table` remains a table when redirected, while
an empty structured Session list remains machine-readable, such as `[]` with
`-f json`.

## Browser Inspection

Use `tabs` to inspect the Session and `snapshot` to read page state.

```bash theme={null}
webcmd --profile work --session work-project-k7 browser tabs
webcmd --profile work --session work-project-k7 browser snapshot
webcmd --profile work --session work-project-k7 browser snapshot --snapshot-mode act
webcmd --profile work --session work-project-k7 browser snapshot --snapshot-mode tree
webcmd --profile work --session work-project-k7 browser snapshot --snapshot-mode read
```

`act` is the action-first snapshot mode, `tree` preserves fuller page structure,
and `read` extracts readable article or content text.

## Browser Programs

Use `browser run` for a small Playwright-style program inside the selected
Session. Exactly one of `--file <path>` or `--stdin` is required.

```bash theme={null}
webcmd --profile work \
  --session work-project-k7 \
  browser run --stdin --timeout 45 <<'JS'
await page.goto('https://example.com');
return { url: page.url(), title: await page.title() };
JS
```

The CLI reads files locally and sends their source, not their path, to the
runtime. `--timeout` is measured in seconds and `--max-output` bounds returned
results and logs. Successful runs include a `snapshotDiff` by default. Use
`--no-snapshot-diff` only when a read-only program already returns all required
state.

Programs run in a fresh QuickJS sandbox with `page`, `context`, `browser`, and
`console` globals. They can use supported Page, Frame, and Locator methods and
passively inspect request and response events. They cannot access Node.js, the
filesystem, environment variables, raw CDP endpoints, browser launch APIs,
browser-context ownership, or `context.newPage()`.

On some local Cloak builds, `page.setContent()` can apply the markup without
resolving because Playwright waits for a console event that build does not emit.
If the call times out, inspect the page before retrying. For this Cloak case,
write the markup directly to keep the page on its current origin:

```js theme={null}
await page.evaluate(html => {
  document.open();
  document.write(html);
  document.close();
}, html);
await page.waitForLoadState('load');
```

The public browser surface is `tabs`, `bind`, `run`, and `snapshot`.

## Direct URL Fetch

For a public URL that does not require browser rendering, an agent can try a
local fetch first:

```bash theme={null}
webcmd web fetch --url https://example.com/article
```

If the result is `FETCH_REQUIRES_BROWSER` or `FETCH_BLOCKED`, continue in an
explicit browser Session. `web fetch` remains local and never opens a browser.

## Browser Selection

Configure local browser mode with `webcmd setup`. Cloak is bundled and selected
by default. Chrome uses an installed Google Chrome with Webcmd-managed Profiles,
SLAB is a macOS alpha option, and an absolute path selects a compatible local
browser executable.

```bash theme={null}
webcmd setup --browser cloak
webcmd setup --browser chrome
webcmd setup --browser slab
webcmd setup --browser /absolute/path/to/browser
webcmd setup --status
```

After changing browsers, restart the daemon if needed and run `webcmd doctor`.
The Chrome transport uses a normal headed launch over a nonzero loopback CDP
port; this is not a claim that Chrome is generally undetectable.

## Profiles

Profiles keep browser identity and sign-in state separate.

```bash theme={null}
webcmd profile list -f json
webcmd profile rename <context-id> work
webcmd profile use work
```

In local mode, arbitrary `--profile <name>` values lazily create separate local
state. In hosted mode, `--profile <name>` selects an identity within the active
workspace. An omitted selector uses that workspace's `default` Profile.

Prompt example:

```text theme={null}
Use the `work` Profile for this Webcmd task. If it is not authenticated, pause
and let me sign in directly in the browser.
```

## Hosted Workspaces

| Flag or environment variable | Purpose |
| - | - |
| `--workspace <id>` | Select the hosted workspace for this invocation. |
| `WEBCMD_WORKSPACE` | Select the hosted workspace when the flag is omitted. |

Resolution order is the flag, then the environment variable, then the implicit
default workspace. Local mode has no workspace concept.

## Hosted Artifacts

Hosted browser receipts retain their `cloud-artifact://` locator and include an
authenticated download URL. Download an artifact with:

```bash theme={null}
webcmd artifact download <download-url> --output <local-path>
```

`--output` is required. Webcmd authenticates the request using the configured
Cloud credentials.

## Top-Level Commands

| Command | Purpose |
| - | - |
| `setup` | Configure the local browser runtime. |
| `doctor` | Diagnose browser runtime and daemon connectivity. |
| `daemon` | Inspect, stop, or restart the local daemon. |
| `session` | Create, list, and close browser Sessions. |
| `browser` | Inspect and operate a live browser Session. |
| `web` | Fetch a public URL without opening a browser. |
| `profile` | List, rename, select, or delete browser Profiles. |
| `auth` | Inspect authentication state and continue sign-in handoffs. |
| `artifact` | Download a hosted browser artifact. |
| `skills` | Install, update, list, or remove the Webcmd browser skill. |
| `completion` | Print shell completion scripts. |

## Output Formats

Commands that return data support `table`, `plain`, `json`, `yaml`, `md`, and
`csv` through `-f/--format`. Agents should normally request JSON; table and
plain formats are easier to read manually.

```bash theme={null}
webcmd session list -f json
webcmd profile list -f table
webcmd doctor -f json
webcmd daemon status -f json
```

`yml` and `markdown` are aliases for `yaml` and `md`.

## Skills

The package ships one agent skill, `webcmd-browser`:

```bash theme={null}
webcmd skills list
webcmd skills add
webcmd skills update
webcmd skills remove
```

On a TTY, `skills add` prompts for any missing scope and agent harness. Use
`--scope <user|project>` and `--provider <agents|codex|claude>` to skip those
prompts, or `--path <skills-dir>` for a custom location.

## Useful Paths

| Path | Purpose |
| - | - |
| `~/.webcmd/` | User-level Webcmd state. |
| `~/.webcmd/cache/browser-network/` | Browser network capture cache. |
| `~/.webcmd/cache/browser-run/` | Browser-run screenshot artifacts. |
| `skills/` | Bundled agent skill shipped with the package. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.