# earl

[![CI](https://github.com/brwse/earl/actions/workflows/ci.yml/badge.svg)](https://github.com/brwse/earl/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/earl)](https://crates.io/crates/earl)
[![docs.rs](https://img.shields.io/docsrs/earl)](https://docs.rs/earl)
[![License: MIT](https://img.shields.io/crates/l/earl)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-brwse.github.io%2fearl-blue)](https://brwse.github.io/earl/docs/)

AI-safe API access for agents — steeped in security.

## The Problem

AI agents with broad shell or network access can read secrets in plaintext and make arbitrary API calls. That's an unacceptable default. See: [clawhub.ai/steipete/trello](https://clawhub.ai/steipete/trello)

## What Earl Does

Earl is the gate between your agent and the network:

- Agents call `earl call 'provider.command(...)'` — not arbitrary `curl`
- Secrets live in the OS keychain, never in CLI output
- Requests are template-driven and reviewed ahead of time
- Outbound traffic can be locked down with `[[network.allow]]` egress rules
- Private IPs are blocked (SSRF protection)

> **Important:** Restrict write access to `~/.config/earl/config.toml` and template files or the security model is undermined.

## Installation

```bash
cargo install earl
```

Building from source requires Node.js and pnpm because Earl embeds the `web` playground assets at compile time.

Or use the installer script:

```bash
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/brwse/earl/main/scripts/install.ps1 | iex
```

## Quick Start

```bash
# Install a template
earl templates install https://raw.githubusercontent.com/brwse/earl/main/examples/github.hcl

# Store a secret
earl secrets set github.token

# Make an API call
earl call 'github.search_issues(query="repo:rust-lang/rust is:issue E-easy", per_page=5)'
```

Launch the local web command catalog + playground:

```bash
earl web
```

## Documentation

[brwse.github.io/earl/docs](https://brwse.github.io/earl/docs/) — [Quick Start](https://brwse.github.io/earl/docs/quick-start) · [Security Model](https://brwse.github.io/earl/docs/security) · [Templates](https://brwse.github.io/earl/docs/templates) · [Configuration](https://brwse.github.io/earl/docs/configuration) · [MCP Integration](https://brwse.github.io/earl/docs/mcp) · [CLI Reference](https://brwse.github.io/earl/docs/commands)

## Release Channels

| Channel    | Tag format    | Publishes to                    |
| ---------- | ------------- | ------------------------------- |
| Stable     | `vX.Y.Z`      | crates.io + GitHub Releases     |
| Prerelease | `vX.Y.Z-rc.N` | Prerelease crate/artifacts only |
