webcmd-usage

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 [email protected]: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:

1. Run webcmd list -f json through a workflow-derived filter before returning its output to the agent.
2. 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 [].
3. 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.
4. 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	background	Explicitly override browser window mode with foreground or background.
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.

Authentication and Human Handoff

If a failure returns handoff.status === action_required, stop before AutoFix. Give the user handoff.action and any Webcmd browser: or handoff.viewUrl link, then wait. After the user reports done, run handoff.verifyCommand when present; verification must succeed before retrying.

AUTH_REQUIRED is not an adapter failure. Run webcmd <site> login: already_logged_in is verified; in_progress means no current user action, so do not ask the user or wait for confirmation, and do not poll; action_required is a hard stop. For action_required, give the user its instructions and any returned action_url or view_url, then wait. If Webcmd returned no URL, use the current visible browser.

Run the returned verify_command (normally webcmd <site> whoami) or handoff.verifyCommand only after the user reports done; verification must succeed before retrying. Without a verifier, take fresh browser state and verify the intended post-action state before any retry, especially for write commands. Use webcmd auth refresh only when an explicit auth-state refresh is needed. Their report alone is not verification. Never request, type, echo, store, or automate passwords, OTPs, recovery codes, cookies, session secrets, or CAPTCHA answers; CAPTCHA stops automation and follows the same verification rule.

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 exte

---

*Content truncated.*