| name | webcmd-usage |
| description | Use at the start of any Webcmd session. This is the top-level map of what `webcmd` can do, how to discover adapters, what flags and output formats are universal, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?". |
| allowed-tools | Bash(webcmd:*), Read |
webcmd-usage
Webcmd turns websites, Electron desktop apps, and external CLIs into a uniform webcmd <site> <command> surface that agents can drive without screen scraping. This skill is the orientation layer. Once you know the task, load the specialized skill that fits it.
The Three Pillars
- Adapter commands:
webcmd <site> <command> [...]. Built-in adapters live in clis/; community adapters promoted to the main repo live as plugins under plugins/; private iteration adapters live in ~/.webcmd/clis/. Each command has a strategy such as PUBLIC, COOKIE, INTERCEPT, UI, or LOCAL.
- Browser driving:
webcmd browser * subcommands (open, state, click, type, select, find, extract, network) for ad-hoc interaction when no adapter covers the task. See webcmd-browser.
- External CLI passthrough:
webcmd gh, webcmd docker, webcmd vercel, and similar wrappers. Manage them with webcmd external install <name> or webcmd external register <name>.
Install
npm install -g @agentrhq/webcmd
webcmd doctor
From source:
git clone git@github.com:agentrhq/webcmd.git
cd webcmd
npm install
npx tsx src/main.ts <command>
webcmd doctor reports daemon status, runtime connection, version checks, and live browser connectivity. It is required for COOKIE, INTERCEPT, UI, and webcmd browser * work. It is not required for PUBLIC, LOCAL, webcmd list, validate, verify, plugin commands, or external CLI passthrough.
Prerequisites By Strategy
| Strategy | Needs |
|---|
PUBLIC | No browser; pure HTTP. |
COOKIE | Logged into the target site in the webcmd-managed browser profile. |
INTERCEPT | Same as COOKIE, plus an automation window to capture a signed request. |
UI | Same as COOKIE, plus full DOM interaction. |
LOCAL | No browser; talks to a local or development endpoint. |
Electron desktop app adapters route through CDP against the running app. Make sure the app is open before invoking those commands.
Discover Commands
Run commands instead of reading static docs:
webcmd
webcmd <site> --help
webcmd <site> <command> --help
Run webcmd with no arguments to see all available functions and installed site adapters. Do not hard-code adapter lists: webcmd list -f json is the source of truth for installed commands and emits one entry per command with fields such as {site, name, aliases, description, strategy, browser, args, columns}.
Large registries can exceed an agent or tool output budget. Filter the JSON stream before it is emitted, using broad literal terms derived from the whole requested workflow:
WORKFLOW_TERMS='["requested action", "output field", "named site"]'
webcmd list -f json | jq --argjson terms "$WORKFLOW_TERMS" '
[.[] | select(
([.site, .name, .description, ((.columns // []) | join(" "))]
| map(. // "") | join(" ") | ascii_downcase) as $text
| any($terms[]; . as $term | $text | contains($term | ascii_downcase))
)]
'
Replace WORKFLOW_TERMS with terms from the current request: the requested action, entity, output fields, and any explicitly named site. Literal matching avoids regex errors from terms such as C++ or [foo]. Do not maintain a site or category allowlist. Match across site, name, description, and columns. If any layer reports truncated output, the inspection is incomplete. Narrow the filter and inspect again. Never treat absence from truncated output as proof that an adapter or plugin is missing, and do not proceed to the next fallback stage from that evidence.
Use this fallback order:
- Run
webcmd list -f json through a workflow-derived filter before returning its output to the agent.
- Check the complete, non-truncated filtered result against the whole requested workflow. If one installed command covers it, use that command and stop discovery. If candidates do not cover the missing capability, refine the capability filter until its complete result is exactly
[].
- Only after that complete filtered result is
[], derive a short plugin query from the missing site or capability and run webcmd plugin search <query> -f json. Preserve the user's term when practical: find flights becomes flight.
- If the complete, non-truncated plugin search returns a match, offer
webcmd plugin install <installSource>. Only if that complete result returns no match and no error is raw webcmd browser allowed. Both plugin search and raw browser fallback require the prior complete filtered registry result to be []. A truncated plugin result is incomplete evidence: refine the query or output before fallback. If plugin search errors, report plugin discovery as unavailable and stop. If fetch failed appears in errors[].message, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve.
Universal Flags
| Flag | Effect |
|---|
-f, --format <fmt> | table in TTY by default; yaml outside TTY by default; also supports json, plain, md, csv. Agents usually want -f json. |
-v, --verbose | Debug logs and stack traces on failure; also sets WEBCMD_VERBOSE=1. |
Command-specific flags such as --limit, --tab, and --filter are not universal. Read <site> <command> --help.
Output Formats
json: pretty-printed, 2-space indent. Best default for agents.plain: prints the primary text field for chat-style commands.yaml: default when output is not a TTY and -f is not explicit.table: color-coded and grouped for humans.md, csv: tabular dumps.
Some commands override the default through cmd.defaultFormat; read --help.
Environment Variables
| Variable | Default | Purpose |
|---|
WEBCMD_BROWSER_CONNECT_TIMEOUT | 45 | Seconds to wait for the browser bridge. |
WEBCMD_BROWSER_COMMAND_TIMEOUT | 60 | Per-command timeout. |
WEBCMD_CDP_ENDPOINT | unset | Manual CDP endpoint override. |
WEBCMD_CACHE_DIR | ~/.webcmd/cache | Network capture and browser-state cache. |
WEBCMD_WINDOW | command-specific | foreground or background browser window mode. |
WEBCMD_VERBOSE | false | Verbose logging, also triggered by -v. |
Self-Repair
When an adapter command fails because a site changed, rerun with:
webcmd <site> <command> [args...] --trace retain-on-failure
The error envelope includes a trace block pointing at summary.md. Patch only adapterSourcePath from that summary and retry. Maximum 3 repair rounds. See webcmd-autofix.
Report A Webcmd Defect
After a reproducible Webcmd failure has been diagnosed or the webcmd-autofix
retry budget is exhausted, load webcmd-autofix and follow its Step 6 reporting
flow. Do not report expected authentication, configuration, CAPTCHA, rate-limit,
argument, transient, or unreproduced failures.
Writing An Adapter
Storage paths:
- Private:
~/.webcmd/clis/<site>/<command>.js
- Public (official bundle):
clis/<site>/<command>.js
- Public (community PRs):
plugins/<site>/ plus root webcmd-plugin.json registration
The main Webcmd repo is itself a plugin monorepo: promoted community CLIs belong under plugins/<site>/ and must be registered in the root webcmd-plugin.json.
Scaffolding and checks:
webcmd browser init <site>/<command>
webcmd validate [target]
webcmd verify [target] [--smoke]
webcmd browser verify <site>/<command>
Adapters import only @agentrhq/webcmd/registry and @agentrhq/webcmd/errors. columns must align one-to-one, in name and order, with returned row object keys. See webcmd-adapter-author.
Plugins
webcmd plugin install github:user/repo
webcmd plugin list [-f json]
webcmd plugin update [name] | --all
webcmd plugin uninstall <name>
webcmd plugin create <name>
webcmd plugin search [query] -f json
webcmd plugin catalog list -f json
webcmd plugin catalog add <source>
webcmd plugin catalog remove <id>
Plugins are installable extensions pulled from git or local paths. Use plugin search for marketplace discovery and plugin list for already-installed plugins. Main-repo community CLIs are exposed through the root plugin catalog manifest, not bundled into npm's clis/ set.
Note: The repository's plugins/ directory is not shipped in the npm package. Find the required plugin with webcmd plugin search, then install its installSource with webcmd plugin install <installSource>.
External CLI Passthrough
webcmd external install gh
webcmd external register my-tool \
--binary my-tool \
--install "npm i -g my-tool" \
--desc "My internal CLI"
webcmd external list
webcmd gh pr list --limit 5
webcmd docker ps
Built-in entries live in src/external-clis.yaml; user overrides live in ~/.webcmd/external-clis.yaml.
Shell Completion
webcmd completion bash
webcmd completion zsh
webcmd completion fish
The script prints to stdout; source or save it according to your shell.
Where To Go Next
| Task | Load |
|---|
| Drive a live browser ad-hoc | webcmd-browser |
| Write a new adapter or command | webcmd-adapter-author |
| Fix a broken adapter after failure | webcmd-autofix |
| Route a search or research request | smart-search |
Removed Commands
Do not invoke these removed commands:
webcmd explore <url>: use webcmd browser network and webcmd browser find, or the webcmd-adapter-author workflow.webcmd record <url>: manual capture now lives in webcmd browser network --detail.- Top-level
webcmd web read / webcmd desktop * groups: use their adapters instead.
Do Not
- Do not paste static command lists into plans; query
webcmd list -f json through a workflow-derived filter.
- Do not emit a large unfiltered registry into a bounded output or infer absence from a truncation warning; filter at the source and narrow until the result is complete.
- Do not assume every adapter needs a browser; check
strategy.
- Do not silently fall back from a failing adapter to hand-rolled
fetch; use --trace retain-on-failure first.
