Skip to content
Back to search

earl

Secure CLI proxy for AI agents — HCL-defined operation templates with OS keychain secrets, MCP integration, and prompt injection protection

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mathematic-inc--earl/badge.svg)](/listings/mathematic-inc--earl)

HTML

<a href="/listings/mathematic-inc--earl"><img src="/api/listings/mathematic-inc--earl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

# Import a provider template
earl templates import https://raw.githubusercontent.com/mathematic-inc/earl/main/examples/3p/github.hcl

# Store a secret — prompts for the value, not echoed
earl secrets set github.token

# Call a command
earl call --yes --json github.search_repos --query "language:rust stars:>100"

To use Earl as MCP tools in your agent, add it to your MCP config and restart. Claude Code and Cursor use the same format:

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

MCP tools don't activate until after restart. In the current session, use `earl call --yes --json` through the Bash tool.

See [Quick Start](https://mathematic-inc.github.io/earl/docs/quick-start/) for the full walkthrough, or [Agent-Assisted Setup](https://mathematic-inc.github.io/earl/docs/agent-assisted-setup/) to let an agent handle the install and configuration.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 96 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="site/public/social-preview.jpg" alt="Earl - AI-safe CLI for AI agents" width="100%" />
  3. </p>
  4. [![CI](https://github.com/mathematic-inc/earl/actions/workflows/ci.yml/badge.svg)](https://github.com/mathematic-inc/earl/actions/workflows/ci.yml)
  5. [![Crates.io](https://img.shields.io/crates/v/earl)](https://crates.io/crates/earl)
  6. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  7. ![HTTP](https://img.shields.io/badge/HTTP-005CDE?logo=curl&logoColor=fff)
  8. ![GraphQL](https://img.shields.io/badge/GraphQL-E10098?logo=graphql&logoColor=fff)
  9. ![gRPC](https://img.shields.io/badge/gRPC-244C5A?logo=google&logoColor=fff)
  10. ![Bash](https://img.shields.io/badge/Bash-4EAA25?logo=gnubash&logoColor=fff)
  11. ![SQL](https://img.shields.io/badge/SQL-%23316192.svg?logo=postgresql&logoColor=white)
  12. &ensp;
  13. [![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](https://github.com/mathematic-inc/earl/releases/latest)
  14. [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://github.com/mathematic-inc/earl/releases/latest)
  15. [![Windows](https://img.shields.io/badge/Windows-0078D4?logo=windows&logoColor=white)](https://github.com/mathematic-inc/earl/releases/latest)
  16. Earl sits between agents and external services. Operations are HCL files committed to your repository. The LLM sees a tool name and description; it never reads the template body. An injected instruction in an API response has nowhere to land because the LLM isn't reading the part of the request that executes.
  17. Secrets stay in the OS keychain. They aren't in tool arguments, tool descriptions, or output.
  18. **[→ Documentation](https://mathematic-inc.github.io/earl/)**
  19. ## Quick start
  20. ```bash
  21. # Install
  22. curl -fsSL https://raw.githubusercontent.com/mathematic-inc/earl/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 29 on GitHub
  23. # Import a provider template
  24. earl templates import https://raw.githubusercontent.com/mathematic-inc/earl/main/examples/3p/github.hcl
  25. # Store a secret — prompts for the value, not echoed
  26. earl secrets set github.token
  27. # Call a command
  28. earl call --yes --json github.search_repos --query "language:rust stars:>100"
  29. ```
  30. To use Earl as MCP tools in your agent, add it to your MCP config and restart. Claude Code and Cursor use the same format:
  31. ```json
  32. {
  33. "mcpServers": {
  34. "earl": {
  35. "command": "earl",
  36. "args": ["mcp", "stdio"]
  37. }
  38. }
  39. }
  40. ```
  41. MCP tools don't activate until after restart. In the current session, use `earl call --yes --json` through the Bash tool.
  42. See [Quick Start](https://mathematic-inc.github.io/earl/docs/quick-start/) for the full walkthrough, or [Agent-Assisted Setup](https://mathematic-inc.github.io/earl/docs/agent-assisted-setup/) to let an agent handle the install and configuration.
  43. ## How it works
  44. You write an HCL template describing an operation: method, URL, auth, parameters. When an agent calls the tool, Earl loads the template, reads the required secret from the OS keychain, renders the Jinja expressions against the agent's supplied values, and executes the request. The LLM only ever provided parameter values. Every other part of the request — the URL, the auth header, the method — was written by a human and committed to the repo.
  45. See [How Earl Works](https://mathematic-inc.github.io/earl/docs/how-earl-works/) for the full security model.
  46. ## Documentation
  47. - [Introduction](https://mathematic-inc.github.io/earl/docs/) — why Earl exists, how the security model works
  48. - [Quick Start](https://mathematic-inc.github.io/earl/docs/quick-start/) — install, first call, MCP config in five steps
  49. - [Template Schema](https://mathematic-inc.github.io/earl/docs/template-schema/) — field-by-field reference
  50. - [Secrets & Auth](https://mathematic-inc.github.io/earl/docs/secrets-and-auth/) — OS keychain storage, OAuth2 flows
  51. - [External Secrets](https://mathematic-inc.github.io/earl/docs/external-secrets/) — 1Password, Vault, AWS, GCP, Azure
  52. - [MCP Integration](https://mathematic-inc.github.io/earl/docs/mcp/) — stdio and HTTP transport, full vs. discovery mode
  53. - [Policy Engine](https://mathematic-inc.github.io/earl/docs/policy-engine/) — JWT auth and access control for HTTP deployments
  54. - [Environments](https://mathematic-inc.github.io/earl/docs/environments/) — production, staging, and per-environment overrides
  55. - [Hardening](https://mathematic-inc.github.io/earl/docs/hardening/) — SSRF protection, egress allowlist, production checklist
  56. - [Commands](https://mathematic-inc.github.io/earl/docs/commands/) — complete CLI reference
  57. - [Troubleshooting](https://mathematic-inc.github.io/earl/docs/troubleshooting/) — keychain errors, template validation, MCP issues
  58. ## Contributing
  59. Start with a [Discussion](https://github.com/mathematic-inc/earl/discussions/new),
  60. not a pull request. A Mathematic maintainer will review the proposal. If we
  61. decide to implement it, a maintainer or one of our AI agents will open the pull
  62. request. GitHub restricts pull request creation to Mathematic maintainers and
  63. repository collaborators with write, maintain, or admin access, plus authorized
  64. maintenance agents.
  65. When Mathematic implements a proposal, the implementation pull request will
  66. link to the Discussion and credit the proposal's original author.
  67. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full policy.
  68. ## License
  69. Apache-2.0
  70. > This project is free and open-source work by a 501(c)(3) non-profit. If you find it useful, please consider [donating](https://github.com/sponsors/mathematic-inc).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.