earl 0.5.2

AI-safe CLI for AI agents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

---
title: Quick Start
icon: Rocket
description: Install Earl, run your first command, and connect it to your agent in under five minutes.
---

This gets you from zero to a working Earl setup: installed, first call returning results, and MCP config ready for your next agent session.

## 1. Install

**macOS / Linux — install script (no Rust required):**

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

**macOS / Linux — cargo:**

```bash
cargo install earl
```

Requires Rust toolchain plus Node.js and pnpm (Earl embeds web playground assets at compile time).

**Windows:**

```powershell
irm https://raw.githubusercontent.com/brwse/earl/main/scripts/install.ps1 | iex
```

After installing, verify:

```bash
earl doctor
```

If `earl doctor` reports errors, see [Troubleshooting](/docs/troubleshooting).

## 2. Import a template

Earl ships with 26 pre-built provider templates. Import GitHub to follow along:

```bash
earl templates import https://raw.githubusercontent.com/brwse/earl/main/examples/github.hcl
```

To see all available templates:

```bash
earl templates list
```

You can also import any pre-built template by replacing `github.hcl` with the provider name — `stripe.hcl`, `slack.hcl`, `openai.hcl`, and so on.

## 3. Store a secret

Secrets go into the OS keychain — the same credential store your password manager uses. The value is never written to disk in plaintext and never enters LLM context.

```bash
earl secrets set github.token
```

Earl prompts for the value. On macOS, the first run may show a system dialog asking for keychain access — click **Always Allow**.

To confirm the key is stored (this shows metadata only, not the value):

```bash
earl secrets list
```

## 4. Run a command

```bash
earl call --yes --json github.search_repos --query "language:rust stars:>100"
```

The `--yes` flag pre-approves the call. The `--json` flag returns structured output instead of the rendered text template. Both flags must come before the command name.

This is what just happened: Earl loaded the `github` template, resolved your token from the keychain, sent the request to `api.github.com`, and returned the result. The token never appeared in the command output.

## 5. Connect to your agent

Add Earl as an MCP server so your agent can call templates as native tools.

**Claude Code** — add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio"]
    }
  }
}
```

**Cursor** — add to `.cursor/mcp.json` (same format).

**Windsurf** — add to `.windsurf/mcp.json` (same format).

**Claude Desktop (macOS)** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`.

After adding the config, **restart your agent**. Earl templates appear as native MCP tools in the next session. In the current session, use `earl call --yes --json` through the Bash tool — MCP tools only activate after restart.

## What's next

- Write your own templates for any API or service: [Template Schema](/docs/template-schema)
- Understand how Earl's security model works: [How Earl Works](/docs/how-earl-works)
- Store OAuth tokens for browser-based auth flows: [Secrets & Auth](/docs/secrets-and-auth)
- Let an agent handle the full setup: [Agent-Assisted Setup](/docs/agent-assisted-setup)