GeezerVison is showing webcmd.dev — Command Surface - Webcmd 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
--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
--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');
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
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
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
--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. |
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
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. |
|