Metadata-Version: 2.4
Name: webpilot-cli
Version: 0.1.0
Summary: pip launcher for the WebPilot browser agent (npm package: @capagents/webpilot)
Author: CLI-Agents
License: MIT
Keywords: webpilot,browser,agent,cli,opentui
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# WebPilot

Self-contained browser agent: OODA loop (observe → orient → decide → act) → Playwright spec.

No FastAPI or database. LLM profiles live in `llms.json`, agent settings in `webpilot.yaml`. The interactive shell is [OpenTUI](https://opentui.com). Headless `run` is for CI.

The loop matches the WebPilot design in test-agent-nexus (`backend/docs/WEBPILOT_FLOW.md`): DOM observe with shadow roots, viewport JPEG, one JSON action per step, then click / type / select / navigate. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [HOW_TO_USE.md](HOW_TO_USE.md).

## Install

OpenTUI needs **Bun 1.3+**. Node cannot load the native renderer.

The CLI is published on **npm** as `@capagents/webpilot` (the unscoped name is too close to an existing package). **PyPI** package `webpilot-cli` is a pip launcher for the same `webpilot` command (`webpilot` is already another project on PyPI).

```bash
curl -fsSL https://bun.sh/install | bash

# npm
npm install -g @capagents/webpilot
npx @capagents/webpilot --help

# pip (launcher; runs the npm package via bun)
pip install webpilot-cli
webpilot --help
```

Live browser profiles also need Chromium: `bunx playwright install chromium`. The `mock` profile does not.

From this repo:

```bash
cd WebPilot
bun install
bun src/index.ts init
bun src/index.ts start
```

One-shot release (same version on both registries; assumes `npm` and `twine` are already logged in):

```bash
./scripts/publish.sh           # current version
./scripts/publish.sh 0.2.0     # bump + publish
./scripts/publish.sh --dry-run # pack only
```

npm is published first. The pip launcher runs `bun x @capagents/webpilot@<version>`.

## Configure

`init` writes:

| File | Purpose |
|------|---------|
| `webpilot.yaml` | Browser, prompts, export, active profile |
| `llms.json` | Named LLM profiles |
| `.env.example` | API key names |

```bash
webpilot models
webpilot run --goal "Read the homepage" --url https://example.com --profile mock --plain
```

`mock` uses a synthetic page, writes `workflow.yaml` and `webpilot.spec.ts`, and does not call a model. Switch `llm.active` to `azure-gpt4o` or `openai-gpt4o` for a real browser run.

## CLI

```bash
webpilot start
webpilot start -u https://example.com -g "Find the documentation link" -p openai-gpt4o

webpilot run --goal "Get a quote" --url https://example.com --profile azure-gpt4o --headed
webpilot run --goal "..." --url https://example.com --profile mock --plain --out ./out/demo
```

Inside the shell: `/url`, `/goal`, `/run`, `/stop`, `/headed`, `/steps`, `/profile`, `/export`, `/exit`. A line without a slash sets the goal and starts when a URL is known.
