Create Template

Create Template

Creates an Earl HCL template file for a specific service and protocol. Each template defines the commands, parameters, authentication, and protocol shape for one provider.

Process

1. Discover — understand what service and command to build
2. Infer protocol — map the user's description to one of Earl's 5 protocols
3. Load reference — read the protocol reference for HCL shapes and patterns
4. Write template — create the HCL file
5. Review — show the user the complete template before running it
6. Validate — run earl templates validate
7. Secrets — print checklist for the human to set secrets
8. Verify — run a test earl call

Phase 1: Discover Intent

If the request doesn't name a provider, command, and protocol, ask one question:

"What service do you want to call, and what should the command do? For example: 'Call the GitHub API to create an issue' or 'Query my PostgreSQL database for user records'."

Check for pre-built templates first

Earl ships with 26 ready-made provider templates. If the user names a known service, check whether it is already imported before offering to import it:

earl templates list

Check the list carefully:

• If the specific command needed is already present (e.g. github.create_issue appears in the list), skip the import and go directly to Phase 7 to set any missing secrets.
• If the provider is imported but the specific command is not in the list (e.g. github commands appear but not github.create_issue), skip the import and proceed to custom template authoring (phases 2–6) to add the missing command to the existing file.
• If the provider is not imported at all, offer to import the pre-built template:

# Available: github, stripe, slack, notion, openai, anthropic, recall_ai, discord, gitlab, jira, linear,
#            pagerduty, twilio, sendgrid, cloudflare, vercel, render, shopify, hubspot,
#            mailchimp, datadog, sentry, airtable, auth0, supabase, resend
earl templates import https://raw.githubusercontent.com/mathematic-inc/earl/main/examples/<provider>.hcl

If a pre-built template was imported, skip to Phase 7: Set Secrets — phases 2–6 are not needed. Then continue to Phase 8 to verify the template works.

Only proceed to custom template authoring (phases 2–6) if no pre-built template covers the needed command.

Phase 2: Infer Protocol

Map the user's description to a protocol:

If the answer is genuinely ambiguous, ask one follow-up question.

SSRF Warning

If the user mentions localhost, 127.0.0.1, 0.0.0.0, or any private IP range (10.x, 172.16-31.x, 192.168.x), warn immediately:

Earl blocks requests to private and loopback IP addresses (SSRF protection). This cannot be bypassed. Use a publicly accessible URL, or use the bash protocol to call local services.

Phase 3: Load Reference

Read the reference file for the chosen protocol before writing any HCL. The reference file contains the complete template shape, required fields, auth patterns, and known gotchas.

Critical rule for all protocols: HCL parses before Jinja renders. All {{ }} expressions must be inside valid HCL string values.

# WRONG — invalid HCL:
params = [{{ args.limit }}]

# CORRECT — Jinja expression inside a string, rendered to a number at call time:
params = ["{{ args.limit }}"]

Phase 4: Draft Template

Do NOT write the file to disk yet. Compose the template content in memory — it will be written to disk only after Phase 5 human review and approval.

Target path (determine now, write after approval):

• Local (project-specific): ./templates/<provider>.hcl
• Global (all projects): ~/.config/earl/templates/<provider>.hcl (macOS/Linux) or %APPDATA%\earl\templates\<provider>.hcl (Windows)

Default to local if the current directory is a project (contains .git/, package.json, Cargo.toml, or similar). Default to global otherwise.

Provider naming: lowercase letters and underscores only. No hyphens, dots, or uppercase. Examples: github, my_company_api, internal_db.

If the file already exists: Read it first. Add the new command block to the existing file rather than overwriting it.

Environments (optional): If the user needs staging/production separation, add an environments block at the provider level. Environment variables are available as vars.* in all template expressions. See the template schema docs for full syntax. Only add environments when the user explicitly needs them — most templates don't.

Template structure:

version = 1
provider = "<provider_name>"

command "<command_name>" {
  title       = "<Short title, shown in tool listings>"
  summary     = "<One-line summary>"
  description = <<-EOT
    <Full description of what this command does.>

    Parameters:
    - param_name: description

    ## Guidance for AI agents
    Use this command to <explain when to use it>.
    Example: `earl call --yes --json <provider>.<command> --param_name value`
  EOT

  annotations {
    mode    = "<read|write>"
    secrets = ["<provider>.<secret_key>"]
  }

  param "<param_name>" {
    type        = "<string|number|boolean>"
    description = "<What this parameter controls>"
    required    = <true|false>
    default     = "<default_value>"   # omit if required = true
  }

  operation {
    protocol = "<http|graphql|grpc|bash|sql>"
    # ... protocol-specific fields from the reference file
  }

  result {
    output = "{{ result }}"
  }
}

Required for every template:

• annotations.mode: "read" if the command reads data, "write" if it creates/modifies/deletes
• annotations.secrets: list all secret keys the template needs (format: "provider.key_name")
• description must include a ## Guidance for AI agents section