v0.5.1

Earl v0.5.1 brings the browser protocol — a full-featured Chrome automation engine baked directly into your HCL templates. With 62 step action variants and Playwright MCP parity, agents can now navigate, scrape, screenshot, click, fill forms, manage cookies, run JavaScript, and interact with the web using the same declarative, auditable, AI-safe template model you already know. Persistent sessions, an accessibility tree renderer for AI-driven interaction, and a brand-new earl runtime skill round out a release that makes Earl a genuinely capable browser automation platform.

---

✨ New Features

Browser Protocol — Chrome automation in HCL

Control Chrome via CDP directly from your Earl templates. Supports both scripted batch workflows (a declarative steps array) and AI-driven interactive sessions (stateful session_id). Ships with the same ~55 actions as the Playwright MCP server — navigation, snapshots, clicks, form fills, mouse events, waits, assertions, JavaScript execution, tab management, cookies, local storage, file uploads, dialogs, PDF export, and more.

Take a full-page screenshot in four lines:

operation {
  protocol = "browser"
  browser {
    headless = true
    steps = [
      { action = "navigate",   url = "{{ args.url }}" },
      { action = "screenshot", full_page = true },
    ]
  }
}

For AI-driven navigation, pass a session_id and the browser stays open between calls — letting an agent snapshot the page, pick an element ref from the accessibility tree, then click it in the next command:

# Step 1 — get the accessibility tree
browser {
  session_id = "{{ args.session_id }}"
  steps = [{ action = "snapshot" }]
}

# Step 2 — click ref e8 (returned by the snapshot)
browser {
  session_id = "{{ args.session_id }}"
  steps = [
    { action = "click", ref = "{{ args.ref }}" },
    { action = "snapshot" },
  ]
}

Four ready-to-use example templates are included under examples/browser/: screenshot.hcl, scrape.hcl, login.hcl, and ai_navigate.hcl.

Security first: only http:// and https:// URLs are allowed in navigate steps (SSRF protection). Sessions are stored at ~/.config/earl/browser-sessions/ with advisory flocks, atomic writes, and 0700 directory permissions. The LLM still never reads the template body — the security model is unchanged.

Earl runtime skill

A new skills/runtime/earl/SKILL.md teaches agents how to use Earl without prior knowledge of what templates are installed. It covers both MCP discovery mode (earl.tool_search + earl.tool_call) and CLI mode, with strict guidance on flag ordering, write-mode permission gating, pagination handling, and a three-tier error resolution ladder. Drop it into your agent config and it will discover and call the right command for any task automatically.

Load it in Claude Code:

/skills add https://raw.githubusercontent.com/brwse/earl/main/skills/runtime/earl/SKILL.md

---

⚡ Improvements

Default browser session

Omitting session_id from a browser operation now defaults to a persistent session named "default" rather than launching a throw-away browser. This makes it trivially easy to chain commands across multiple tool calls without passing a session ID every time. To opt back into ephemeral behavior, pass an explicit empty string: session_id = "".

Skills reorganised by audience

All agent skills have been moved into two clearly labelled categories:

• skills/development/ — setup, template authoring, migration, security hardening, troubleshooting
• skills/runtime/ — the new earl skill for agents calling commands at runtime

Protocol-first documentation

The Templates section of the docs has been restructured around protocols (HTTP, GraphQL, gRPC, Bash, SQL, Browser) rather than generic template concepts, making it faster to find syntax for the protocol you're actually using.

Third-party provider examples

Community-contributed provider templates have moved to examples/3p/ to keep the core examples/ directory clean.

---

Install / Upgrade

# Shell one-liner (macOS & Linux)
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/scripts/install.sh | bash

# Or via Cargo
cargo install earl

Full documentation at brwse.github.io/earl.