Getting Started
Webcmd turns a demonstrated browser task into a reusable app capability, workflow, or generated CLI. It records a real session, prepares evidence packets for an agent, writes a typed capability graph, and materializes deterministic artifacts that can be verified and run without rediscovering the app.
Webcmd requires Node >= 20.
npm install -g @agentrhq/webcmd
webcmd --help
# one-off
npx @agentrhq/webcmd --help
The fast path
This is the normal create flow from an empty workspace:
webcmd setup
# shell 1: keep the browser session alive
webcmd open "https://news.ycombinator.com" --session hn --headed
# shell 2: inspect or drive the session
webcmd snapshot --session hn
webcmd click --session hn --role link --name "new"
webcmd network summary --session hn
# close writes the next-step hint when recording was enabled
webcmd close --session hn
# prepare a distillation packet from the recorded evidence
webcmd distill prepare --session hn \
--sample-task "Collect top Hacker News stories" \
--sample limit=10
# after an agent writes .webcmd/sessions/hn/distill.plan.json
webcmd distill apply .webcmd/sessions/hn/distill.plan.json
# turn the graph into a workflow or a CLI
webcmd workflow hacker-news --task "Collect top Hacker News stories"
webcmd workflow hacker-news --plan .webcmd/graphs/hacker-news/workflow.plan.json
webcmd cli hacker-news --task "Create a CLI for top stories"
webcmd cli hacker-news --plan .webcmd/graphs/hacker-news/cli.plan.json --install-skill
webcmd verify .webcmd/exports/workflows/news.ycombinator.com/top-stories.mjs
webcmd run news.ycombinator.com/top-stories --limit 10
What each command produces
| Step | Command | Main output |
|---|---|---|
| Install skills | webcmd setup | Webcmd authoring skills in ~/.agents/skills/ or .agents/skills/. |
| Record | webcmd open | .webcmd/sessions/<session>/journal.jsonl, snapshots, network evidence, session metadata. |
| Inspect | webcmd snapshot, webcmd journal, webcmd network * | Semantic page snapshots, compact event log, redacted request records and reviewer marks. |
| Distill | webcmd distill prepare | .webcmd/sessions/<session>/distill.packet.json plus network-candidates.json. |
| Apply graph changes | webcmd distill apply | .webcmd/graphs/<app-id>/capabilities.json. |
| Materialize workflow | webcmd workflow <app-id> --task/--plan | .webcmd/exports/workflows/<domain>/<workflow-id>.mjs. |
| Materialize CLI | webcmd cli <app-id> --task/--plan | .webcmd/exports/clis/<domain>/, optional installed generated skill. |
| Verify | webcmd verify <target> | Structured pass/fail report for a workflow script or generated CLI directory. |
Authoring packets decide the next phase
When you do not know whether to record more evidence, distill, build, or repair, ask Webcmd for an authoring packet:
webcmd author cli --operation create \
--task "Create a CLI that lists saved jobs" \
--app-id linkedin \
--url https://www.linkedin.com
webcmd author workflow --operation heal \
--task "Existing export no longer finds result rows" \
--app-id linkedin \
--target .webcmd/exports/workflows/www.linkedin.com/search-jobs.mjs
The packet lives under .webcmd/authoring/ and includes the phase (discovery, distill, build, or repair), the known graph/workflow/CLI evidence, discovery budget, required reading list, and concrete next actions.
Sessions record by default
webcmd open records unless you pass --no-record. A recording session captures browser actions, semantic snapshots, and redacted network records. The command stays running because it owns the browser and its control server; use another shell for snapshot, click, fill, press, wait, goto, handoff, resume, and close.
Use --profile <name> or --user-data-dir <absolute-path> when the app needs auth. Generated workflows that set auth: true reuse .webcmd/profiles/default unless the caller overrides the profile.