Metadata-Version: 2.4
Name: webctl
Version: 0.2.0
Summary: Browser automation via CLI — for humans and agents
Project-URL: Homepage, https://github.com/cosinusalpha/webctl
Project-URL: Repository, https://github.com/cosinusalpha/webctl
Project-URL: Issues, https://github.com/cosinusalpha/webctl/issues
Author-email: cosinusalpha <42695699+cosinusalpha@users.noreply.github.com>
License: MIT
Keywords: agent,automation,browser,cli,web
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: aiofiles>=24.0.0
Requires-Dist: deepdiff>=7.0.0
Requires-Dist: lark>=1.1.0
Requires-Dist: markdownify>=0.13.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-playwright>=0.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-aiofiles>=24.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# webctl

**Browser automation for AI agents and humans, built on the command line.**

```bash
# 1. Install
pip install webctl

# 2. Auto-configure your agent (creates skills/prompts for all supported agents)
webctl init

# 3. Start browsing
webctl start
webctl navigate "https://google.com"
webctl snapshot --interactive-only
```

**`webctl init` automatically generates the skills and prompts your agents need to drive the browser.**

## Why CLI Instead of MCP?

MCP browser tools have a fundamental problem: **the server controls what enters your context**. With Playwright MCP, every response includes the full accessibility tree plus console messages. After a few page queries, your context window is full.

CLI flips this around: **you control what enters context**.

```bash
# Filter before context
webctl snapshot --interactive-only --limit 30      # Only buttons, links, inputs
webctl snapshot --within "role=main"               # Skip nav, footer, ads

# Pipe through Unix tools
webctl snapshot | grep -i "submit"                 # Find specific elements
webctl --format jsonl snapshot | jq '.data.role'   # Extract with jq
```

Beyond filtering, CLI gives you:

| Capability         | CLI                           | MCP                    |
|--------------------|-------------------------------|------------------------|
| **Filter output**  | Built-in flags + grep/jq/head | Server decides         |
| **Debug**          | Run same command as agent     | Opaque                 |
| **Cache & Cost**   | `webctl snapshot > cache.txt` | Every call hits server |
| **Script**         | Save to .sh, version control  | Ephemeral              |
| **Human takeover** | Same commands                 | Different interface    |

---

## Agent Integration

**Step 1: Install**

```bash
pip install webctl
webctl setup  # Downloads Chromium
```

**Step 2: Generate Skills/Prompts**

```bash
webctl init              # Project-level (recommended)
webctl init --global     # Global (works across all projects)
```

This creates:

- **Skills** for Claude Code and Goose (loaded on-demand when doing web tasks)
- **Lean prompts** for Gemini, Copilot, and Codex (always in context)

**Supported agents:**

| Agent            | Format | Location (project)                | Location (global)                         |
|------------------|--------|-----------------------------------|-------------------------------------------|
| `claude`         | Skill  | `.claude/skills/webctl/SKILL.md`  | `~/.claude/skills/webctl/SKILL.md`        |
| `goose`          | Skill  | `.agents/skills/webctl/SKILL.md`  | `~/.config/agents/skills/webctl/SKILL.md` |
| `gemini`         | Prompt | `GEMINI.md`                       | `~/.gemini/GEMINI.md`                     |
| `copilot`        | Prompt | `.github/copilot-instructions.md` | -                                         |
| `codex`          | Prompt | `AGENTS.md`                       | `~/.codex/AGENTS.md`                      |
| `claude-noskill` | Prompt | `CLAUDE.md` (legacy)              | `~/.claude/CLAUDE.md`                     |

**Why skills?** Skills are loaded on-demand - your agent only reads webctl instructions when actually doing web automation. This keeps your context clean for other tasks.

**Select specific agents:**

```bash
webctl init --agents claude,gemini    # Only Claude and Gemini
webctl init --agents claude-noskill   # Legacy CLAUDE.md format
```

**Step 3: Add to Config (optional)**

If your agent doesn't auto-detect the generated files, add this to your system prompt:

> For web browsing, use webctl CLI. Run `webctl agent-prompt` for instructions.

*Note: If a browser MCP is already configured, disable it to avoid conflicts.*

---

## Quick Start (Human Usage)

Verify the installation works by driving it yourself:

```bash
webctl start                    # Opens visible browser window
webctl navigate "https://example.com"
webctl snapshot --interactive-only
webctl stop --daemon            # Closes browser and daemon
```

<details>
<summary>Global installation with `uv`</summary>

```bash
uv tool install webctl
uv tool run webctl
```

</details>

<details>
<summary>Linux system dependencies</summary>

```bash
playwright install-deps chromium
# Or manually install libraries listed in Playwright documentation
```

</details>

---

## Core Concepts

### Sessions

Browser stays open across commands. Cookies persist to disk.

```bash
webctl start                    # Visible browser
webctl start --mode unattended  # Headless (invisible)
webctl -s work start            # Named profile (separate cookies)
```

### Element Queries

Semantic targeting based on ARIA roles - stable across CSS refactors:

```bash
role=button                     # Any button
role=button name="Submit"       # Exact match
role=button name~="Submit"      # Contains text (preferred)
```

### Output Control

```bash
webctl snapshot                                    # Human-readable
webctl --quiet navigate "..."                      # Suppress events
webctl --result-only --format jsonl navigate "..." # Pure JSON
```

---

## Commands

### Navigation & Observation

```bash
webctl navigate "https://..."
webctl back / forward / reload
webctl snapshot --interactive-only        # Buttons, links, inputs only
webctl snapshot --within "role=main"      # Scope to container
webctl query "role=button name~=Submit"   # Debug query
webctl screenshot --path shot.png
```

### Interaction

```bash
webctl click 'role=button name~="Submit"'
webctl type 'role=textbox name~="Email"' "user@example.com"
webctl type 'role=textbox name~="Search"' "query" --submit
webctl select 'role=combobox name~="Country"' --label "Germany"
webctl check 'role=checkbox name~="Remember"'
webctl press Enter
webctl scroll down
```

### Wait Conditions

```bash
webctl wait network-idle
webctl wait 'exists:role=button name~="Continue"'
webctl wait 'url-contains:"/dashboard"'
```

### Session & Console

```bash
webctl status                   # Current state & error counts
webctl save                     # Persist cookies now
webctl console --count          # Just counts by level (LLM-friendly)
webctl console --level error    # Filter to errors only
```

---

## For AI Agents

*This section is designed to be read by AI agents directly.*

### webctl Quick Reference

Control a browser via CLI. Start with `webctl start`, end with `webctl stop --daemon`.

**Commands:**

```bash
webctl start                              # Open browser
webctl navigate "URL"                     # Go to URL
webctl snapshot --interactive-only        # See clickable elements
webctl click 'role=button name~="Text"'   # Click element
webctl type 'role=textbox name~="Field"' "text" --submit  # Type + Enter
webctl wait 'exists:role=button name~="..."'              # Wait for element
webctl stop --daemon                      # Close browser
```

**Query syntax:**

- `role=button` - By ARIA role (button, link, textbox, combobox, checkbox)
- `name~="partial"` - Partial match (preferred, more robust)

**Tips:**

- Use `--interactive-only` to reduce output (only buttons, links, inputs)
- Use `name~=` for partial matching (handles minor text changes)
- Use `webctl query "..."` if element not found - shows suggestions
- Check `webctl status` for console error counts before investigating

---

## Architecture

```
┌─────────────┐     TCP/IPC      ┌─────────────┐
│   CLI       │ ◄──────────────► │   Daemon    │
│  (webctl)   │    JSON-RPC      │  (browser)  │
└─────────────┘                  └─────────────┘
      │                                 │
      ▼                                 ▼
  Agent/User                      Chromium + Playwright
```

- **CLI**: Stateless, sends commands to daemon
- **Daemon**: Manages browser, auto-starts on first command
- **Profiles**: `~/.local/share/webctl/profiles/`

---

## License

MIT
