Command Surface

Most people should start with the Prompt Cookbook 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.

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.

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.

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:

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:

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.

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.

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:

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:

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.

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:

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.

Start

Agent Harnesses

Understand Webcmd

Build and Share

Use Cases

Reference and Support

Command Surface

Command Surface

Sessions

Browser Inspection

Browser Programs

Direct URL Fetch

Browser Selection

Profiles

Hosted Workspaces

Hosted Artifacts

Top-Level Commands

Output Formats

Skills

Useful Paths

​Command Surface

​Sessions

​Browser Inspection

​Browser Programs

​Direct URL Fetch

​Browser Selection

​Profiles

​Hosted Workspaces

​Hosted Artifacts

​Top-Level Commands

​Output Formats

​Skills

​Useful Paths

Command Surface

Sessions

Browser Inspection

Browser Programs

Direct URL Fetch

Browser Selection

Profiles

Hosted Workspaces

Hosted Artifacts

Top-Level Commands

Output Formats

Skills

Useful Paths