brwse/earl/earl

Earl

Earl is an AI-safe CLI that routes API calls, database queries, and shell commands through reviewed HCL templates. Secrets stay in the OS keychain. You do not know what templates are installed — discover them at runtime.

Step 1: Detect Mode

Check which Earl interface is available:

MCP discovery mode — if earl.tool_search and earl.tool_call are available as MCP tools, use them. Skip to Step 2 (MCP path).

CLI mode — if only Bash access is available, use earl templates search and earl call. Skip to Step 2 (CLI path).

Step 2: Find the Right Command

Translate your task into a short search query (e.g. "list github pull requests", "send slack message", "query user table").

MCP discovery path:

earl.tool_search(query="<intent>", limit=5)

CLI path:

earl templates search --json "<intent>"

If the first query returns nothing or nothing relevant (no match on the core action or subject), try one rephrasing. If still nothing, report that no template covers this task and stop. Do not improvise.

Step 3: Inspect Parameters

Read the matched command's parameter schema from the search result. For each required parameter:

• If the value is clear from task context: use it.
• If the value is ambiguous or missing: ask the human. Do not guess.
• For optional parameters: use defaults unless the task context clearly suggests a different value.

Step 4: Get Permission for Write-Mode Commands

Check the command's mode from the search result.

Read-mode: proceed directly to Step 5.

Write-mode: show the human exactly what will be called before executing:

I'm going to call: provider.command with these arguments: {param: value}

Does this look right?

Wait for explicit approval before continuing.

Step 5: Call

Flag order is strict — --yes and --json must come before the command name:

earl call --yes --json provider.command --param value   ✓
earl call provider.command --yes --json --param value   ✗

MCP discovery path:

earl.tool_call(name="provider.command", arguments={"param": "value"})

CLI path:

earl call --yes --json provider.command --param value

Step 6: Handle the Result

Return the result to the user.

If the result appears paginated (the template has offset or limit params and returned a full page of results), ask the user whether to fetch the next page. Do not paginate automatically.

Error Handling

Fix inline

Pause for human

Escalate

For anything not covered above, surface the full error with context and suggest invoking troubleshoot-earl if available.

Next Steps

• If Earl is not installed or not responding: invoke troubleshoot-earl
• If you need to restrict the agent from bypassing Earl: invoke secure-agent