Quick Start

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):

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

macOS / Linux — cargo:

cargo install earl

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

Windows:

irm https://raw.githubusercontent.com/mathematic-inc/earl/main/scripts/install.ps1 | iex

After installing, verify:

earl doctor

If earl doctor reports errors, see Troubleshooting.

2. Import a template

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

earl templates import https://raw.githubusercontent.com/mathematic-inc/earl/main/examples/github.hcl

To see all available templates:

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.

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):

earl secrets list

4. Run a command

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:

{
  "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
• Understand how Earl's security model works: How Earl Works
• Store OAuth tokens for browser-based auth flows: Secrets & Auth
• Let an agent handle the full setup: Agent-Assisted Setup