CLI Reference

Global Behavior

Earl reads configuration from ~/.config/earl/config.toml. Templates are loaded from ./templates/ (local, relative to cwd) and ~/.config/earl/templates/ (global). All commands that load templates merge both directories.

Environment Variables

RUST_LOG=debug earl call github.search_issues --query "test"

Exit Codes

earl call

Execute a template command.

earl call <provider.command> [--key value ...] [--yes] [--json]

The first argument is the command key in provider.command form. Remaining arguments are passed as --key value pairs that bind to the template's declared parameters.

Write-mode commands prompt for explicit confirmation unless --yes is passed.

Examples

# Read-mode call with parameters
earl call github.search_issues --query "repo:rust-lang/rust is:issue E-easy" --per_page 5

# Write-mode call, auto-approved
earl call github.create_issue --repo "myorg/myrepo" --title "Bug report" --yes

# JSON output for scripting
earl call stripe.list_charges --limit 10 --json | jq '.result'

earl templates

Work with templates. The --json flag is available globally on all subcommands.

earl templates list

List all loaded template commands.

earl templates list [--category <category>] [--mode read|write] [--json]

# List all templates
earl templates list

# Only write-mode templates, as JSON
earl templates list --mode write --json

earl templates search

Semantic search over template descriptions and metadata. Uses a local embedding model by default; optionally backed by a remote search endpoint if configured.

earl templates search '<query>' [--limit <n>] [--json]

earl templates search "list open pull requests" --limit 5

earl templates validate

Validate all template files in local and global template directories. Returns a list of validated files, or exits with an error on the first validation failure.

earl templates validate [--json]

# Human-readable output
earl templates validate

# JSON list of validated file paths
earl templates validate --json

earl templates import

Import a template from a local file path or a direct HTTP(S) URL to a .hcl file.

earl templates import <source> [--scope local|global] [--json]

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

# Import from URL into global scope
earl templates import https://example.com/templates/slack.hcl --scope global

earl templates generate

Generate a template by delegating to a coding CLI. Earl builds a structured prompt from your description and pipes it into the specified CLI's stdin.

earl templates generate -- <cli> [args...]

Everything after -- is the coding CLI invocation. Earl will interactively ask you to describe the template you want before sending the prompt.

# Delegate to Claude Code
earl templates generate -- claude --dangerously-skip-permissions

# Delegate to any coding CLI
earl templates generate -- my-coding-cli --flag

earl secrets

Manage secrets in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

earl secrets set

Store a secret value. Prompts interactively for the value by default.

earl secrets set <key> [--stdin]

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

# Pipe from an environment variable
printf '%s' "$GITHUB_TOKEN" | earl secrets set github.token --stdin

earl secrets get

Show metadata for a stored secret.

earl secrets get <key>

earl secrets list

List all stored secret keys with their timestamps.

earl secrets list

earl secrets delete

Delete a secret from the keychain.

earl secrets delete <key>

earl auth

Manage OAuth2 authentication profiles. Each <profile> argument must match a [auth.profiles.<profile>] section in config.toml.

Supported OAuth flows: auth_code_pkce, device_code, client_credentials.

earl auth login

Start the OAuth login flow for a profile.

earl auth login <profile>

earl auth login github

earl auth status

Show current token status for a profile (logged in, expiration, scopes).

earl auth status <profile>

earl auth refresh

Force an immediate token refresh for a profile.

earl auth refresh <profile>

earl auth logout

Delete the stored token for a profile.

earl auth logout <profile>

earl mcp

Run an MCP (Model Context Protocol) server for AI agent integration. Each template command is exposed as an MCP tool.

earl mcp [stdio|http] [--listen <addr>] [--mode full|discovery] [--yes]

Examples

# Default: stdio transport, full mode
earl mcp

# stdio with write-mode tools enabled

earl mcp stdio --yes

# HTTP transport on default port
earl mcp http

# HTTP on custom address with discovery mode
earl mcp http --listen 0.0.0.0:9000 --mode discovery --yes

earl doctor

Diagnose configuration and setup issues. Runs a series of checks and prints a summary report.

earl doctor [--json]

Checks Performed

# Human-readable report
earl doctor

# Machine-readable JSON
earl doctor --json

The command exits with code 1 if any check has error status.

earl web

Launch a local web server with documentation and a playground for loaded template tools.

earl web [--listen <addr>] [--no-open]

The server prints its URL and a bearer token on startup. Press Ctrl+C to stop.

# Default: random port, opens browser
earl web

# Fixed port, no browser
earl web --listen 127.0.0.1:3000 --no-open

earl completion

Generate shell completion scripts.

earl completion <shell>

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

earl completion bash > ~/.local/share/bash-completion/completions/earl

earl completion zsh > ~/.zfunc/_earl
# Ensure ~/.zfunc is in your fpath

earl completion fish > ~/.config/fish/completions/earl.fish

earl completion powershell >> $PROFILE