> ## Documentation Index > Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI command reference > Reference every Webcompute CLI command, argument, option, and operational caveat. The Webcompute CLI command is `web`. Older installs may also expose `webcompute`, but new docs and examples use `web`. Start with the [quickstart](/quickstart) for the shortest first run. Stay here for exact command and flag coverage. ## Global flags Global flags can be passed before a subcommand. | Flag | Description | | --------------------- | ------------------------------------------------------------------------------------------------ | | `-V, --version` | Print the CLI version. | | `-k, --api-key ` | Use this Webcompute API key for the current invocation. Overrides environment and stored config. | | `-u, --api-url ` | Use this Gateway URL for the current invocation. Overrides environment and stored config. | | `-j, --json` | Prefer machine-readable JSON output when the command supports it. | | `-v, --verbose` | Print verbose diagnostics and expanded error details. | ## Top-level commands | Command | Purpose | | ---------------------- | ------------------------------------------------------------------------------- | | `web setup` | Configure local Webcompute plugin integrations for detected coding-agent hosts. | | `web browser` | Manage cloud browsers and browser runtime resources. | | `web agent ` | Run a model-backed browser agent from the terminal. | | `web scrape ` | Read a URL through an ephemeral browser. | | `web screenshot ` | Capture an image of a URL through an ephemeral browser. | | `web pdf ` | Generate a PDF from a URL through an ephemeral browser. | | `web status` | Check service and auth readiness. | | `web doctor` | Diagnose local install, MCP, and plugin setup. | | `web mcp` | Configure or run the Webcompute MCP server. | | `web plugins` | Detect, install, update, inspect, and remove local plugin artifacts. | | `web config` | Read and write local CLI config. | | `web model` | Manage local model profiles used by `web agent` and MCP `run_web_agent`. | | `web login ` | Save a Webcompute API key in local config. | | `web logout` | Remove the stored API key from local config. | | `web update` | Update the local CLI, MCP server, and plugins. | | `web install` | Install Webcompute locally. | | `web uninstall` | Remove the managed local install. | ## `web agent` ```bash theme={null} web agent [options] ``` `web agent` is the fastest path to a useful browser-agent run. It creates or reuses a browser, lets the configured model issue bounded browser tool calls, and returns a final answer. ```bash theme={null} web agent \ --url https://www.sec.gov/edgar/search/ \ --allow-domain sec.gov \ "Find Apple's latest 10-Q filings. Return filing date, accession number, filing URL, and a one-sentence summary." ``` | Option | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `--url ` | Starting URL for the agent run. | | `--profile ` | Saved model profile name. | | `--model ` | Explicit model ID, or a saved profile name. | | `--route ` | Override model route. Accepted routes: `openai`, `openrouter`, `openai-compatible`, `anthropic`, `google`. | | `--base-url ` | Base URL for an `openai-compatible` route. | | `--model-api ` | Provider API family for compatible routes. Accepted values: `chat-completions`, `responses`. | | `--api-key-env ` | Environment variable containing the model-provider API key. | | `--allow-domain ` | Repeatable browser navigation allow-list. Each value is passed into browser policy `allowedDomains`. | | `--max-turns ` | Maximum model turns for the run. | | `--max-tool-calls ` | Maximum browser tool calls for the run. | | `--timeout-ms ` | Whole-run timeout in milliseconds. | | `--tool-timeout-ms ` | Per browser tool execution timeout in milliseconds. | | `--approval ` | Confirmation mode. Accepted values: `ask`, `delegated`, `never`. Defaults to `delegated` when not set. | | `--secret ` | Repeatable env-backed secret variable. The agent sees `name`; the value is loaded from `ENV_VAR` only when an approved tool call needs it. | | `--schema ` | Path to a JSON schema for final structured output. | | `--json` | Print a machine-readable run envelope. | | `--quiet` | Print the final answer only. | | `--show-usage` | Compatibility flag. Usage appears in the footer when available. | | `--verbose` | Include agent diagnostic details. | | `--debug-url` | Reveal a signed Debug UI URL. In JSON mode this appears at `browser.debugUrl`. Treat it like a bearer credential until it expires. | `web agent` does not expose a `--proxy` flag. Use the TypeScript SDK with `web.agent({ browser: { create: { proxy } } })` when an agent run must create its browser through a custom proxy. ## `web browser` Browser commands operate on managed cloud browsers. Most commands also honor global `--json` and `--verbose`. ### Browser lifecycle | Command | Options | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `web browser create` | `--proxy `, `--max-duration `, `--recording` | Create a cloud browser. `--proxy` routes browser traffic through the supplied proxy URL. `--max-duration` sets the browser lifetime in milliseconds. `--recording` enables browser recording. | | `web browser list` | `--status `, `--limit `, `--cursor `, `--created-after `, `--created-before ` | List browsers. Status values are `creating`, `ready`, `stopping`, `stopped`, `resuming`, `recovering`, `closing`, `closed`, `failed`. Timestamps must be ISO strings. | | `web browser get ` | None | Fetch browser details. | | `web browser status ` | None | Fetch compact runtime status for a browser. | | `web browser stop ` | None | Stop a browser while retaining recoverable state. | | `web browser resume ` | None | Resume a stopped browser. | | `web browser close ` | None | Close a browser. | | `web browser cdp ` | None | Print a signed Chrome DevTools Protocol WebSocket URL. | | `web browser debug ` | None | Print a signed Debug UI URL for live inspection. | `web browser cdp` and `web browser debug` return signed bearer URLs. Do not paste them into shared prompts, logs, or tickets unless you intend to grant access. ### Browser blockers and pages | Command | Options | Description | | ------------------------------------------ | ------------------- | --------------------------------------------------------------------------------- | | `web browser captcha-status ` | None | Fetch compact CAPTCHA and blocker status. | | `web browser captcha-resolve ` | `--timeout-ms ` | Ask the runtime to resolve a detected CAPTCHA blocker, waiting up to the timeout. | | `web browser pages ` | None | List known browser pages and active-page metadata. | ### Dialogs and downloads | Command | Options | Description | | ------------------------------------------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `web browser dialogs ` | `--page-id `, `--status `, `--cursor `, `--limit ` | List JavaScript dialogs. Status values are `open` and `recent`. | | `web browser dialog ` | `--prompt-text ` | Accept or dismiss a JavaScript dialog. `action` must be `accept` or `dismiss`; `--prompt-text` applies to prompt dialogs when accepting. | | `web browser downloads ` | None | List browser downloads. | | `web browser download ` | `-o, --output `, `--overwrite`, `--max-bytes ` | Inspect a download, or save it locally when `--output` is set. `--overwrite` replaces an existing file. `--max-bytes` caps saved bytes. | ### Advanced browser-code execution ```bash theme={null} web browser run --code "return await page.title()" ``` | Option | Description | | --------------------------- | --------------------------------------------------------------------------------------------------- | | `--code ` | Inline browser-code body. | | `--file ` | Path to a JavaScript or TypeScript browser-code snippet. Use either `--code` or `--file`, not both. | | `--page-id ` | Target a known non-active page. Omit for ordinary active-page work. | | `--timeout-ms ` | Execution timeout in milliseconds. | | `--screenshot ` | Screenshot capture mode: `never`, `on_error`, or `always`. | | `--no-status` | Do not include compact runtime status in the response. | | `--no-observe` | Do not include automatic post-step page observation. | | `--observe-kind ` | Observation kind: `aria`, `text`, or `none`. | | `--observe-depth ` | ARIA observation depth. | | `--observe-max-chars ` | Maximum observation characters. | | `--observe-timeout-ms ` | Observation timeout in milliseconds. | | `--observe-boxes` | Include element boxes in ARIA observation when supported. | ### Recordings Recording commands require the browser to have been created with recording enabled. | Command | Options | Description | | ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------ | | `web browser recording ` | None | Show the browser recording summary. | | `web browser recording segments ` | None | List recording segments. | | `web browser recording open ` | None | Show one segment manifest. | | `web browser recording download ` | `-o, --output ` | Download the segment manifest, events, and frames into a local directory. Defaults to `.`. | ## Quick actions Quick actions create an ephemeral browser for one deterministic operation. ### `web scrape` ```bash theme={null} web scrape [options] ``` | Option | Description | | ----------------------- | ----------------------------------------------------------------------------------- | | `-f, --format ` | Output format. Accepted values: `markdown`, `html`, `text`. Defaults to `markdown`. | | `--wait-for ` | Wait for a CSS selector before reading. | | `--selector ` | CSS selector that scopes page content. | | `--iframe ` | CSS selector of a specific iframe to target. | | `--max-chars ` | Soft cap on returned content characters. Valid range: `1` to `50000`. | | `--include-links` | Include deterministic anchor links in the output. | | `--iframe-text` | When the format is not `html`, append iframe text to content. | | `--proxy ` | Proxy URL for the ephemeral browser. | ### `web screenshot` ```bash theme={null} web screenshot [options] ``` | Option | Description | | ----------------------- | ------------------------------------------------- | | `-o, --output ` | Output file path. | | `--full-page` | Capture the full scrollable page. | | `--format ` | Image format: `png` or `jpeg`. Defaults to `png`. | | `--quality ` | JPEG quality from `1` to `100`. | | `--selector ` | CSS selector of an element to capture. | | `--wait-for ` | Wait for a CSS selector before capture. | | `--proxy ` | Proxy URL for the ephemeral browser. | ### `web pdf` ```bash theme={null} web pdf [options] ``` | Option | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | `-o, --output ` | Output file path. | | `--format ` | Page size. Accepted values: `Letter`, `A4`, `A3`, `Tabloid`, `Ledger`, `Legal`. Defaults to `Letter`. | | `--landscape` | Use landscape orientation. | | `--wait-for ` | Wait for a CSS selector before PDF generation. | | `--proxy ` | Proxy URL for the ephemeral browser. | ## MCP commands ### `web mcp run` Run the MCP server. Stdio transport is the default. | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | | `--transport ` | MCP transport: `stdio` or `http`. | | `--host ` | HTTP host. HTTP transport must bind to a loopback host. | | `--port ` | HTTP port. | | `--surface ` | MCP surface: `runtime`, `agent`, or `all`. Defaults to `runtime`. | | `--model ` | Model profile for `agent` or `all` surfaces. Requires `--surface agent` or `--surface all`. | | `--allow-origin ` | Repeatable allowed browser origin for MCP-created browsers. | | `--allow-domain ` | Repeatable allowed browser domain for MCP-created browsers. | | `--private-access ` | Repeatable private-access scope. Current CLI support is `localhost`. | ### `web mcp setup [target]` Write MCP config for an agent target. Supported targets are `claude`, `codex`, `opencode`, `cursor`, `devin`, `openclaw`, and `hermes`. | Option | Description | | --------------------- | ------------------------------------------------------------------------------------------- | | `--scope ` | Host-specific scope such as `user` or `project`. | | `--surface ` | MCP surface: `runtime`, `agent`, or `all`. | | `--model ` | Model profile for `agent` or `all` surfaces. Requires `--surface agent` or `--surface all`. | | `--instructions` | Install a host-native Webcompute instruction artifact where safe. | | `--force` | Replace an existing non-managed Webcompute entry. | | `--dry-run` | Print the proposed mutation without writing. | | `--json` | Output raw JSON. | | `--quiet` | Suppress non-error output. | `--agent` is not a supported shorthand. Use `--surface agent --model `. ### Other MCP commands | Command | Options | Description | | ------------------------- | ------------------------------------------ | ---------------------------------------- | | `web mcp config [target]` | `--surface `, `--model ` | Print read-only MCP config for a target. | | `web mcp doctor` | `--json`, `--quiet` | Check local MCP readiness. | ## Model profile commands `web model setup` starts a guided setup flow in an interactive terminal. For automation, pass `--route`, `--model`, and the other values directly. | Command | Options | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `web model setup` | `--name `, `--route `, `--model `, `--api-key-env `, `--base-url `, `--model-api `, `--default`, `--json`, `--quiet` | Create or update a model profile. Routes are `openai`, `openrouter`, `openai-compatible`, `anthropic`, and `google`. Model APIs are `chat-completions` and `responses`. `--json` is non-interactive; `--quiet` suppresses success output after a fully specified save. | | `web model list` | `--json` | List saved model profiles. | | `web model show [profile]` | `--json`, `--sdk` | Show one model profile, or the default profile when omitted. `--sdk` prints copy-paste SDK code that uses the same model settings explicitly. | | `web model use ` | None | Set the default model profile. | | `web model doctor [profile]` | `--json` | Check profile readiness and credential env state. | | `web model unset ` | None | Delete a model profile. | ## Plugin commands Supported plugin targets are `claude`, `codex`, and `opencode`. | Command | Options | Description | | ------------------------------------ | -------------------------------- | --------------------------------------------------------------------------------- | | `web plugins detect` | `--json`, `--quiet`, `--verbose` | Detect supported local agent tools. | | `web plugins list` | `--json`, `--quiet`, `--verbose` | List supported plugin targets and install state. | | `web plugins install ` | `--json`, `--quiet`, `--verbose` | Install Webcompute plugin artifacts for the specified targets. | | `web plugins update [targets...]` | `--json`, `--quiet`, `--verbose` | Reapply installed plugin artifacts. Omit targets to update all installed targets. | | `web plugins doctor [targets...]` | `--json`, `--quiet`, `--verbose` | Check plugin payloads and config drift. | | `web plugins uninstall ` | `--json`, `--quiet`, `--verbose` | Remove Webcompute plugin artifacts. | ## Local install commands `web install`, `web setup`, `web update`, and `web uninstall` share local lifecycle options. | Option | Description | | ---------------------- | ----------------------------------------------------------------- | | `--channel ` | Release channel. | | `--version ` | Exact release version. | | `--manifest-url ` | Explicit release manifest URL. | | `--plugins ` | Plugin targets as comma-separated names: `claude,codex,opencode`. | | `--no-plugins` | Skip plugin setup. | | `--yes` | Accept defaults and run non-interactively. | | `--no-modify-path` | Do not modify shell profile PATH blocks. | | `--json` | Output raw JSON. | | `--quiet` | Reduce human-readable output. | | `--verbose` | Print verbose output. | Additional lifecycle options: | Command | Extra option | Description | | --------------- | ------------------- | ------------------------------------------------------------ | | `web install` | `--allow-downgrade` | Allow installing an older release. | | `web update` | `--allow-downgrade` | Allow updating to an older release. | | `web uninstall` | `--purge` | Also remove Webcompute-owned config, cache, state, and logs. | ## Config and auth commands | Command | Options | Description | | ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `web config set ` | None | Set a local config value. Valid keys are `apiKey`, `serverUrl`, and `debug`. Boolean strings `true` and `false` are stored as booleans. | | `web config get ` | None | Print a local config value. `apiKey` is masked. | | `web config list` | None | Print all stored local config values. `apiKey` is masked. | | `web config unset ` | None | Remove a local config value. | | `web login ` | None | Save a Webcompute API key. Keys must start with `wc_key_`. | | `web logout` | None | Remove the stored API key. | | `web status` | None | Check Gateway health and auth readiness. | | `web doctor` | `--json` | Diagnose local install, MCP, and plugin setup. |