Commands

Earl has seven subcommands: call, templates, secrets, auth, mcp, doctor, and web. There's also completion for shell completions.

earl call

Execute a provider command.

earl call [--yes] [--json] [--env <name>] <provider.command> [--param value ...]

Flag ordering matters. --yes and --json must come before provider.command. Anything after provider.command is treated as template parameters.

# Correct
earl call --yes --json github.create_issue --owner myorg --repo myrepo --title "Bug fix"

# Wrong — --yes will not be parsed as a flag here
earl call github.create_issue --yes --owner myorg

Flags

Parameters

Template parameters follow the command name as --param-name value pairs:

earl call github.search_repos --query "language:rust stars:>100"
earl call stripe.list_customers --limit 10 --status active

Parameter names correspond to param blocks in the template. Required parameters that are missing cause an error before the request goes out.

Write-mode confirmation

Any command annotated mode = "write" pauses and asks before running:

Command `github.create_issue` is write-enabled.
Type YES to continue:

Pass --yes to skip the prompt. This is required for write commands running in automated pipelines, CI, or MCP servers where stdin is not interactive.

Examples

# Basic read call
earl call github.search_repos --query "language:rust"

# Write call with confirmation bypassed
earl call --yes github.create_issue --owner myorg --repo myrepo --title "Bug fix"

# JSON output for scripting
earl call --json stripe.list_customers --limit 10

# Both flags, staging environment
earl call --yes --json --env staging github.create_issue --owner myorg --repo myrepo --title "Fix"

# Pipe JSON output to jq
earl call --json github.search_repos --query "rust" | jq '.items[].full_name'

earl templates

Work with template files.

earl templates [--json] <subcommand>

--json is a global flag for earl templates that applies to any subcommand.

list

List all loaded templates and their commands.

earl templates list
earl templates list --category scm
earl templates list --mode read

search

Semantic search over template commands. Useful for finding commands by intent rather than exact name.

earl templates search "find open pull requests"
earl templates search "send slack message" --limit 5

validate

Validate all template files in the local and global template directories. Exits non-zero if any file fails to parse or fails validation.

earl templates validate

Validation checks: HCL parse errors, unknown fields, mismatched secrets (auth references a secret not declared in annotations.secrets), and schema errors.

import

Import a template from a local file path or a direct HTTPS URL to an .hcl file.

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

# From local file
earl templates import ./my-provider.hcl

# Import to global config dir instead of ./templates
earl templates import https://example.com/provider.hcl --scope global

Local templates (./templates/) take precedence and are visible only in the current project directory. Global templates (~/.config/earl/templates/) are available in all projects.

generate

Generate a template by sending a structured prompt to a coding CLI. The coding CLI receives the prompt on stdin and writes the template.

earl templates generate -- claude --dangerously-skip-permissions
earl templates generate -- aider --yes

Everything after -- is the coding CLI invocation. Earl prompts for a description of what you want, builds a detailed prompt from the template schema, and pipes it to the CLI.

earl secrets

Manage secrets in the OS keychain.

Earl uses the OS credential store: System Keychain on macOS, Secret Service via libsecret on Linux, Windows Credential Manager on Windows. Values are never written to disk in plaintext.

set

Store a secret value.

# Interactive prompt (value is not echoed)
earl secrets set github.token

# From stdin — useful in scripts and CI
echo "ghp_xxxx" | earl secrets set github.token --stdin
cat token-file.txt | earl secrets set service.api_key --stdin

On macOS, the first write to the keychain may show a system dialog asking for permission. Click "Always Allow".

get

Show metadata for a stored secret. Never shows the value.

earl secrets get github.token

Output includes the key name, creation time, and last-updated time. The value field always shows [REDACTED]. There is no flag to print the raw value.

list

List all stored secret keys.

earl secrets list

delete

Remove a secret from the keychain.

earl secrets delete github.token

earl auth

Manage OAuth2 authentication profiles. Profiles are defined in ~/.config/earl/config.toml under [auth.profiles.<name>]. See Configuration for profile setup.

login

Start the OAuth2 flow for a profile.

earl auth login myprofile

The behavior depends on the configured flow:

• auth_code_pkce — opens a browser; a human must authorize
• device_code — prints a URL and code; a human enters the code on any device; Earl polls
• client_credentials — completes immediately; no human needed

Tokens are stored in the OS keychain under oauth2.<profile>.token.

status

Check whether a profile has a valid token and when it expires.

earl auth status myprofile

Output includes logged_in, expires_at, and scopes.

refresh

Force a token refresh for a profile. Earl normally refreshes automatically when a token is about to expire; this is for forcing a refresh manually.

earl auth refresh myprofile

logout

Remove the stored token for a profile. The next earl auth login will start the full OAuth flow again.

earl auth logout myprofile

earl mcp

Run Earl as an MCP server. Templates appear as MCP tools.

earl mcp <stdio|http> [flags]

The transport (stdio or http) is a positional argument. Defaults to stdio.

stdio transport

Standard input/output transport. This is what most agent platforms use.

# Basic stdio server
earl mcp stdio

# Discovery mode: expose a meta-tool that searches templates,
# instead of exposing every command as a separate tool
earl mcp stdio --mode discovery

# Pre-approve write calls (required for write commands in automated flows)
earl mcp stdio --yes

Most agent config looks like this:

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

http transport

HTTP transport for multi-user, multi-agent deployments. Requires JWT auth configured in config.toml unless --allow-unauthenticated is passed.

# Production — requires [auth.jwt] in config.toml
earl mcp http --listen 0.0.0.0:8977

# Local development only
earl mcp http --listen 127.0.0.1:8977 --allow-unauthenticated

Do not use --allow-unauthenticated on a shared host or in production.

Flags

Two-session model

MCP tools do not activate in the current session. After adding Earl to your agent's MCP config, restart the agent. Templates appear as native tools in the next session.

In the current session, call Earl through the terminal:

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

After restarting, use Earl tools natively. See Agent-Assisted Setup for more.

earl doctor

Diagnose configuration and setup problems.

earl doctor
earl doctor --json    # machine-readable output

Doctor runs these checks:

• Config file: can it be found and parsed?
• Network allowlist: how many rules are configured?
• Template files: are any found in ./templates/ or ~/.config/earl/templates/?
• Template validation: do all templates pass schema validation?
• Commands: does the catalog load and have at least one command?
• Required secrets: are all secrets declared in template annotations present in the keychain?
• OAuth profiles: do templates reference profiles that are configured?
• Remote search: if enabled, is it configured correctly?
• JWT config: is [auth.jwt] set up correctly?
• Policy rules: are [[policy]] entries well-formed?
• Bash sandbox tool: is the sandbox executable available?

Each check reports ok, warning, or error. Doctor exits non-zero if any check is an error.

earl web

Launch the local web playground.

earl web
earl web --no-open    # don't auto-open the browser

The playground serves on a random available port. Earl prints the URL and an auth token on startup.

earl completion

Generate shell completion scripts.

earl completion bash   >> ~/.bashrc
earl completion zsh    >> ~/.zshrc
earl completion fish   > ~/.config/fish/completions/earl.fish
earl completion powershell
earl completion elvish

Supported shells: bash, zsh, fish, powershell, elvish.