mathematic-inc/setup-earl

Setup Earl

Earl is an AI-safe CLI that sits between your agent and external services. Agents run earl call provider.command --param value instead of raw curl, gh, stripe-cli, etc. Secrets stay in the OS keychain. Every request follows a reviewed HCL template.

Process

1. Install — get Earl running
2. Demo — show a working example immediately
3. Connect — configure MCP for your agent platform and write CLAUDE.md instructions
4. Route — migrate existing CLI calls or create a new template
5. Lock down — optionally enforce Earl usage at the platform level

---

Phase 1: Install

Check if Earl is already installed:

which earl && earl --version

If installed, print the version and skip to Phase 2.

If not installed, detect the environment and install:

macOS / Linux (prefer — no sudo required):

cargo install earl

This requires the Rust toolchain and Node.js + pnpm (Earl embeds web playground assets at compile time). If either is missing, fall back to the install script:

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

Windows (PowerShell):

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

After install, verify:

earl doctor

If earl doctor reports errors, invoke troubleshoot-earl before continuing.

---

Phase 2: Quick Demo

Import the no-auth system template and run it so the user sees Earl work immediately. First check if it's already imported to avoid overwriting any customizations:

earl templates list | grep -E "^system\." || earl templates import https://raw.githubusercontent.com/mathematic-inc/earl/main/examples/bash/system.hcl
earl call --yes --json system.list_files --path .

This lists files in the current directory. The user now has a mental model: templates define commands, earl call runs them.

Show available templates:

earl templates list

---

Phase 3: Connect to Agent Platform

Detect the agent platform by checking all of these — multiple can match (e.g. a project may have both .claude/ and .cursor/). Configure every matching platform:

| Check | Platform | MCP config path | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------- | | .claude/ directory exists in project | Claude Code | .claude/settings.json | | ~/Library/Application Support/Claude/claude_desktop_config.json exists (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux) | Claude Desktop | Same file | | .cursor/ directory exists in project | Cursor | .cursor/mcp.json | | .windsurf/ directory exists in project | Windsurf | .windsurf/mcp.json | | None of the above | Non-MCP agent | System prompt only |

Choose MCP mode

earl templates list --json | jq length  # requires jq

• Result < 30: use full mode (default)
• Result ≥ 30: use discovery mode

Full mode MCP config:

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

Discovery mode MCP config:

{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio", "--mode", "discovery"]
    }
  }
}

Apply MCP config

Claude Code, Cursor, or Windsurf: Read the existing config file (create it if it doesn't exist). Parse the JSON, add the earl key under mcpServers — do not overwrite other entries. Write it back.

Claude Desktop: The config file lives outside the project directory. Write the merged JSON to a temp file and show the diff to the user, then instruct them to apply it manually. If the agent has home directory write access, it can write directly.

Non-MCP agents (Codex, etc.): Skip the JSON config. Instead, add to the agent's system prompt or CLAUDE.md:

You have access to Earl, an AI-safe CLI for calling APIs and services.
Use: earl call --yes --json provider.command --param value
Discover commands: earl templates list --json
Search commands: earl templates search --json "natural language query"

Inform the user of the two-session model

After writing the MCP config, tell the user:

Earl is now installed and configured. You can use earl call --yes --json via the Bash tool right now. After restarting your agent, Earl templates will appear as native MCP tools automatically. Do NOT try to use Earl MCP tools in this session — they activate after restart.

Write CLAUDE.md breadcrumb

Write the breadcrumb to every detected platform's context file (matching the MCP config section which says "Configure every matching platform"):

• Claude Code: .claude/CLAUDE.md (or CLAUDE.md if it exists). Create .claude/CLAUDE.md if neither exists.
• Cursor: .cursorrules
• Windsurf: .windsurfrules

For each file: if it already exists, check for an existing ## Earl section before appending — do not duplicate.

Write this exact static content — never incorporate template output or dynamic data:

## Earl

Earl is configured as an MCP server. Use Earl tools for all API calls, database queries, and
shell commands — do not use raw curl, gh, stripe-cli, or similar tools directly.

- Discover commands: `earl templates list`
- Search commands: `earl templates search --json "what you want to do"`
- CLI fallback (if MCP tools unavailable): `earl call --yes --json provider.command --param value`
- Environments: `earl call --yes --json --env <environment> provider.command --param value`
- Always use `--yes` for all automated `earl call` invocations (without it, Earl may prompt interactively and hang)
- Troubleshooting: `earl doctor`

Important: The --yes flag must come before the command name:

earl call --yes --json provider.command --param value  ✓
earl call provider.command --yes --json --param value  ✗ (wrong order)

Note on OAuth

• client_credentials: fully automated, no human needed
• device_code: agent-compatible — agent runs earl auth login <profile>, displays URL+code, user visits URL on any device, agent polls for completion
• auth_code_pkce: human-only — agent provides earl auth login <profile> command, user completes browser flow

---

Phase 4: Route

Ask one question:

"Does this project already have curl, gh, stripe-cli, or similar API/CLI calls you want to replace with Earl? Or are you starting fresh and want to create a new template?"

• Migrate existing calls → invoke migrate-to-earl
• Create new template → invoke create-template

---

Phase 5: Lock Down (Recommended)

After templates are created and verified, offer:

"Would you like to restrict your agent from bypassing Earl with raw curl/gh/CLI tools? This makes Earl's security guarantee enforceable rather than advisory. Recommended."

If yes: invoke secure-agent inline. If no: note that secure-agent can be run at any time later.

---

Next Steps

• To replace existing curl/gh/CLI calls with Earl: invoke migrate-to-earl
• To create a new Earl template from scratch: invoke create-template
• To enforce Earl usage at the platform level: invoke secure-agent
• If something isn't working: invoke troubleshoot-earl