Template Schema Reference

Templates are version = 1 HCL files. Each file declares a provider namespace and one or more command blocks. This page documents every field, type, and default value.

Root Fields

Field	Type	Required	Default	Description
`version`	`integer`	Yes	--	Must be `1`.
`provider`	`string`	Yes	--	Namespace for commands (e.g., `github`). Must not be empty.
`categories`	`string[]`	No	`[]`	Provider-level categories applied to all commands in the file.
`command "<name>"`	block	Yes	--	One or more named command blocks. At least one is required.

Commands are identified by provider.command (e.g., github.search_issues).

`command`

command "search_issues" {
  title       = "Search Issues"
  summary     = "Search GitHub issues using a query string"
  description = "Detailed markdown description..."
  categories  = ["search"]

  annotations { ... }
  param "query" { ... }
  operation { ... }
  result { ... }
}

Field	Type	Required	Default	Description
`title`	`string`	Yes	--	Human-readable title. Must not be empty.
`summary`	`string`	Yes	--	One-line summary. Must not be empty.
`description`	`string`	Yes	--	Detailed markdown description. Must not be empty.
`categories`	`string[]`	No	`[]`	Command-level categories (merged with provider categories).
`annotations`	block	Yes	--	Mode and secret declarations.
`param`	block(s)	No	`[]`	Repeatable typed input parameters.
`operation`	block	Yes	--	Protocol-specific execution definition.
`result`	block	Yes	--	Output decoding, extraction, and rendering.

`annotations`

annotations {
  mode    = "read"
  secrets = ["github.token"]
}

Field	Type	Required	Default	Description
`mode`	`"read"` \| `"write"`	Yes	--	Safety mode. Write-mode commands require user confirmation.
`secrets`	`string[]`	No	`[]`	Secret keys this command is allowed to access. Auth blocks that reference a secret must declare it here.

`param`

Parameters define typed inputs. Use the block syntax param "<name>" { ... } for each parameter.

param "query" {
  type        = "string"
  required    = true
  description = "GitHub search query"
}

param "limit" {
  type    = "integer"
  default = 10
}

Field	Type	Required	Default	Description
`name`	`string`	Yes	--	Parameter name (inferred from the block label). Must be unique within a command.
`type`	`string`	Yes	--	One of: `string`, `integer`, `number`, `boolean`, `null`, `array`, `object`.
`required`	`boolean`	No	`false`	Whether the argument must be provided.
`default`	`any`	No	--	Default value used when the argument is not provided.
`description`	`string`	No	--	Human-readable description shown in help and MCP tool schemas.

Parameter Type Details

Type	CLI Input	Description
`string`	`--name value`	Passed as-is.
`integer`	`--name 42`	Parsed as a signed 64-bit integer.
`number`	`--name 3.14`	Parsed as a 64-bit float.
`boolean`	`--name` or `--name true`	Bare `--flag` is treated as `true`.
`null`	`--name null`	Only the literal `null` is accepted.
`array`	`--name '[1,2,3]'`	Parsed as a JSON array.
`object`	`--name '{"k":"v"}'`	Parsed as a JSON object.

`operation`

The operation block defines what earl executes. The protocol field selects the operation shape.

Protocol	Description	Feature Flag
`http`	Standard HTTP request	`http` (default)
`graphql`	GraphQL over HTTP POST	`graphql` (default)
`grpc`	gRPC over HTTP/2	`grpc` (default)
`bash`	Sandboxed Bash script execution	`bash` (default)
`sql`	Parameterized SQL query execution	`sql` (default)

HTTP Operation

operation {
  protocol = "http"
  method   = "GET"
  url      = "https://api.example.com/items"
  path     = "/{{ args.item_id }}"
  query    = { q = "{{ args.query }}" }
  headers  = { Accept = "application/json" }
  cookies  = { session = "{{ args.sid }}" }

  auth { ... }
  body { ... }
  transport { ... }
}

Field	Type	Required	Default	Description
`protocol`	`string`	Yes	--	Must be `"http"`.
`method`	`string`	Yes	--	HTTP method (`GET`, `POST`, `PUT`, `DELETE`, etc.). Must not be empty.
`url`	`string`	Yes	--	Base URL for the request. Must not be empty. Supports template expressions.
`path`	`string`	No	--	Path appended to `url`. Supports template expressions.
`query`	`map<string, any>`	No	--	Query string parameters. Keys and values support template expressions.
`headers`	`map<string, any>`	No	--	HTTP headers. Keys and values support template expressions.
`cookies`	`map<string, any>`	No	--	Cookies sent with the request. Keys and values support template expressions.
`auth`	block	No	--	Authentication configuration. See auth.
`body`	block	No	--	Request body configuration. See body.
`transport`	block	No	--	Transport options (timeouts, retries, TLS). See transport.

GraphQL Operation

operation {
  protocol = "graphql"
  url      = "https://api.example.com/graphql"
  headers  = { Authorization = "Bearer {{ secrets.myapi.token }}" }

  graphql {
    query          = "query User($id: ID!) { user(id: $id) { login email } }"
    operation_name = "User"
    variables = {
      id = "{{ args.user_id }}"
    }
  }

  auth { ... }
  transport { ... }
}

Field	Type	Required	Default	Description
`protocol`	`string`	Yes	--	Must be `"graphql"`.
`method`	`string`	No	`"POST"`	Must be `POST` when provided.
`url`	`string`	Yes	--	GraphQL endpoint URL. Must not be empty.
`path`	`string`	No	--	Path appended to `url`.
`query`	`map<string, any>`	No	--	URL query parameters (not the GraphQL query).
`headers`	`map<string, any>`	No	--	HTTP headers.
`cookies`	`map<string, any>`	No	--	Cookies.
`auth`	block	No	--	Authentication. See auth.
`graphql`	block	Yes	--	GraphQL query definition.
`transport`	block	No	--	Transport options. See transport.

`graphql` block

Field	Type	Required	Default	Description
`query`	`string`	Yes	--	GraphQL query or mutation string. Must not be empty.
`operation_name`	`string`	No	--	GraphQL operation name (for documents with multiple operations).
`variables`	`any`	No	--	Variables passed to the GraphQL operation. Supports template expressions.

gRPC Operation

operation {
  protocol = "grpc"
  url      = "http://127.0.0.1:50051"
  headers  = { x-request-id = "{{ args.request_id }}" }

  auth { ... }

  grpc {
    service             = "grpc.health.v1.Health"
    method              = "Check"
    body                = { service = "" }
    descriptor_set_file = "./descriptors/health.fds.bin"
  }

  transport { ... }
}

Field	Type	Required	Default	Description
`protocol`	`string`	Yes	--	Must be `"grpc"`.
`url`	`string`	Yes	--	gRPC server URL. Must not be empty.
`headers`	`map<string, any>`	No	--	gRPC metadata headers.
`auth`	block	No	--	Authentication. For gRPC, `api_key.location` must be `header`. See auth.
`grpc`	block	Yes	--	gRPC call definition.
`transport`	block	No	--	Transport options. `proxy_profile` and `tls.min_version` are not supported for gRPC.

`grpc` block

Field	Type	Required	Default	Description
`service`	`string`	Yes	--	Fully qualified gRPC service name (e.g., `grpc.health.v1.Health`). Must not be empty.
`method`	`string`	Yes	--	RPC method name (e.g., `Check`). Must not be empty.
`body`	`object` or `array`	No	--	Request message. An object for unary/server-streaming calls, or an array of objects for client-streaming.
`descriptor_set_file`	`string`	No	--	Path to a protobuf file descriptor set (`.fds.bin`). If omitted, earl uses server reflection. Must not be empty when provided.

Bash Operation

Requires the bash feature flag. Bash scripts run in a sandboxed environment. The global sandbox configuration in config.toml can further restrict execution.

operation {
  protocol = "bash"

  bash {
    script = "du -sh {{ args.path }}"
    env = {
      MY_VAR = "{{ args.value }}"
    }
    cwd = "/tmp"
    sandbox {
      network        = false
      writable_paths = ["output/"]
      max_time_ms    = 5000
      max_output_bytes = 1048576
    }
  }

  transport { ... }
}

Field	Type	Required	Default	Description
`protocol`	`string`	Yes	--	Must be `"bash"`.
`bash`	block	Yes	--	Bash execution definition.
`transport`	block	No	--	Transport options (only `timeout_ms` is typically relevant).

`bash` block

Field	Type	Required	Default	Description
`script`	`string`	Yes	--	Bash script to execute. Supports template expressions. Must not be empty.
`env`	`map<string, any>`	No	--	Environment variables passed to the script. Values support template expressions.
`cwd`	`string`	No	--	Working directory for the script.
`sandbox`	block	No	--	Sandbox restrictions.

`bash.sandbox` block

Field	Type	Required	Default	Description
`network`	`boolean`	No	--	Allow network access from the script.
`writable_paths`	`string[]`	No	--	Relative paths the script may write to. Must not contain absolute paths or `..` segments.
`max_time_ms`	`u64`	No	--	Maximum execution time in milliseconds.
`max_output_bytes`	`u64`	No	--	Maximum combined stdout+stderr size in bytes.

SQL Operation

Requires the sql feature flag. SQL queries use parameterized placeholders (?) instead of template expressions in the query string. Jinja2 expressions ({{ }}) are not allowed in sql.query.

operation {
  protocol = "sql"

  sql {
    connection_secret = "analytics.database_url"
    query             = "SELECT id, customer, total FROM orders ORDER BY created_at DESC LIMIT ?"
    params            = ["{{ args.limit }}"]
    sandbox {
      read_only  = true
      max_rows   = 100
      max_time_ms = 5000
    }
  }

  transport { ... }
}

Field	Type	Required	Default	Description
`protocol`	`string`	Yes	--	Must be `"sql"`.
`sql`	block	Yes	--	SQL query definition.
`transport`	block	No	--	Transport options.

`sql` block

Field	Type	Required	Default	Description
`connection_secret`	`string`	Yes	--	Secret key containing the database connection URL. Must not be empty. Must be declared in `annotations.secrets`.
`query`	`string`	Yes	--	SQL query to execute. Use `?` for parameterized values. Must not be empty. Must not contain `{{` or `}}`.
`params`	`any[]`	No	--	Positional parameters bound to `?` placeholders in the query. Values support template expressions. Wrap Jinja expressions in quotes (e.g., `["{{ args.limit }}"]`) so the HCL parser sees valid string tokens. Pure expressions like `"{{ args.limit }}"` are automatically parsed as JSON, so integers and other types are preserved.
`sandbox`	block	No	--	Sandbox restrictions.

`sql.sandbox` block

Field	Type	Required	Default	Description
`read_only`	`boolean`	No	--	Restrict to read-only queries. The `sandbox.sql_force_read_only` setting in `config.toml` can override this to `true`.
`max_rows`	`u64`	No	--	Maximum number of rows to return. The `sandbox.sql_max_rows` setting in `config.toml` can cap this further.
`max_time_ms`	`u64`	No	--	Maximum query execution time in milliseconds.

The auth block configures authentication for HTTP, GraphQL, and gRPC operations. The kind field selects the authentication strategy. All secrets referenced in auth must be declared in annotations.secrets.

Sends an Authorization: Bearer <token> header.

auth {
  kind   = "bearer"
  secret = "github.token"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"bearer"`.
`secret`	`string`	Yes	Secret key containing the bearer token.

Sends an API key as a header, query parameter, or cookie.

auth {
  kind     = "api_key"
  location = "header"
  name     = "X-API-Key"
  secret   = "service.api_key"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"api_key"`.
`location`	`"header"` \| `"query"` \| `"cookie"`	Yes	Where to send the API key. For gRPC, must be `"header"`.
`name`	`string`	Yes	Header name, query parameter name, or cookie name.
`secret`	`string`	Yes	Secret key containing the API key value.

Sends an Authorization: Basic <base64(username:password)> header.

auth {
  kind            = "basic"
  username        = "{{ args.username }}"
  password_secret = "service.password"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"basic"`.
`username`	`string`	Yes	Username. Supports template expressions.
`password_secret`	`string`	Yes	Secret key containing the password.

Uses an OAuth2 profile configured in config.toml to obtain an access token. The token is sent as a Bearer header.

auth {
  kind    = "oauth2_profile"
  profile = "my_provider"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"oauth2_profile"`.
`profile`	`string`	Yes	Name of the OAuth2 profile defined in configuration.

Explicitly disables authentication.

auth {
  kind = "none"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"none"`.

`body`

The body block configures the request body for HTTP operations. The kind field selects the body format. Not available for gRPC, Bash, or SQL operations.

Sends a JSON request body with Content-Type: application/json.

body {
  kind = "json"
  value = {
    title = "{{ args.title }}"
    body  = "{{ args.body }}"
    labels = {{ args.labels }}
  }
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"json"`.
`value`	`any`	Yes	JSON value to send. Supports template expressions.

Sends URL-encoded form data with Content-Type: application/x-www-form-urlencoded.

body {
  kind = "form_urlencoded"
  fields = {
    grant_type = "client_credentials"
    scope      = "{{ args.scope }}"
  }
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"form_urlencoded"`.
`fields`	`map<string, any>`	Yes	Form fields. Values support template expressions.

Sends multipart form data. Each part must specify exactly one of value, bytes_base64, or file_path.

body {
  kind = "multipart"
  parts = [
    {
      name  = "file"
      file_path    = "{{ args.file }}"
      content_type = "application/octet-stream"
      filename     = "upload.bin"
    },
    {
      name  = "description"
      value = "{{ args.description }}"
    }
  ]
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"multipart"`.
`parts`	`array`	Yes	Array of part objects. Must include at least one part.

Multipart Part Fields

Field	Type	Required	Description
`name`	`string`	Yes	Form field name.
`value`	`string`	No	Text value. Mutually exclusive with `bytes_base64` and `file_path`.
`bytes_base64`	`string`	No	Base64-encoded binary content. Mutually exclusive with `value` and `file_path`.
`file_path`	`string`	No	Path to a file to upload. Mutually exclusive with `value` and `bytes_base64`.
`content_type`	`string`	No	MIME type for this part.
`filename`	`string`	No	Filename sent in the multipart Content-Disposition header.

Sends a raw text body.

body {
  kind         = "raw_text"
  value        = "{{ args.payload }}"
  content_type = "text/plain"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"raw_text"`.
`value`	`string`	Yes	Text content. Supports template expressions.
`content_type`	`string`	No	MIME type override.

Sends raw binary data from a base64-encoded string.

body {
  kind         = "raw_bytes_base64"
  value        = "{{ args.encoded_data }}"
  content_type = "application/octet-stream"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"raw_bytes_base64"`.
`value`	`string`	Yes	Base64-encoded binary content.
`content_type`	`string`	No	MIME type override.

Streams a file as the request body.

body {
  kind         = "file_stream"
  path         = "{{ args.file_path }}"
  content_type = "application/octet-stream"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"file_stream"`.
`path`	`string`	Yes	Path to the file. Must not be empty. Supports template expressions.
`content_type`	`string`	No	MIME type override.

Explicitly sends no request body.

body {
  kind = "none"
}

Field	Type	Required	Description
`kind`	`string`	Yes	Must be `"none"`.

`transport`

Optional transport configuration for timeouts, retries, redirects, TLS, compression, and proxying. Available on all protocols.

transport {
  timeout_ms         = 30000
  max_response_bytes = 10485760
  compression        = true
  proxy_profile      = "corp"

  redirects {
    follow   = true
    max_hops = 5
  }

  retry {
    max_attempts    = 3
    backoff_ms      = 250
    retry_on_status = [429, 502, 503]
  }

  tls {
    min_version = "1.2"
  }
}

Top-level Transport Fields

Field	Type	Required	Default	Description
`timeout_ms`	`u64`	No	--	Request timeout in milliseconds. Must be greater than 0.
`max_response_bytes`	`u64`	No	--	Maximum response body size in bytes. Must be greater than 0.
`compression`	`boolean`	No	--	Enable response decompression.
`proxy_profile`	`string`	No	--	Named proxy profile from `config.toml` `network.proxy_profiles`. Must not be empty when provided. Not supported for gRPC.

`transport.redirects`

Field	Type	Required	Default	Description
`follow`	`boolean`	No	`true`	Whether to follow HTTP redirects.
`max_hops`	`integer`	No	`5`	Maximum number of redirect hops.

`transport.retry`

Field	Type	Required	Default	Description
`max_attempts`	`integer`	No	`0`	Maximum number of retry attempts.
`backoff_ms`	`u64`	No	`250`	Backoff between retries in milliseconds.
`retry_on_status`	`integer[]`	No	`[]`	Status codes that trigger a retry. For HTTP/GraphQL these are HTTP status codes; for gRPC these are gRPC status code numbers.

`transport.tls`

Field	Type	Required	Default	Description
`min_version`	`string`	No	--	Minimum TLS version. Accepted values: `"1.0"`, `"1.1"`, `"1.2"`, `"1.3"`. Not supported for gRPC.

`result`

The result block controls how the response is decoded, optionally extracted, and rendered to output.

result {
  decode       = "json"
  extract {
    json_pointer = "/items"
  }
  output       = "Found {{ result | length }} items"
  result_alias = "items"
}

Field	Type	Required	Default	Description
`decode`	`string`	No	`"auto"`	Decode strategy for the response body.
`extract`	block	No	--	Optional extraction rule applied after decoding.
`output`	`string`	Yes	--	Jinja2 template for the human-readable output. Must not be empty.
`result_alias`	`string`	No	--	Additional variable name for `result` in the output template.

`result.decode` Values

Value	Description
`auto`	Automatically detect the format from Content-Type headers.
`json`	Parse the response body as JSON.
`text`	Treat the response body as plain text.
`html`	Treat the response body as HTML (enables `css_selector` extraction).
`xml`	Treat the response body as XML (enables `xpath` extraction).
`binary`	Treat the response body as binary data.

`result.extract` Shapes

Exactly one extraction field must be provided in the extract block. Each shape requires a compatible decode mode.

Extracts a value from a JSON response using an RFC 6901 JSON Pointer.

extract {
  json_pointer = "/items/0/name"
}

Field	Type	Required	Description
`json_pointer`	`string`	Yes	JSON Pointer path (e.g., `/items/0`). Requires `decode = "json"` or `"auto"` with JSON response.

Extracts text using a regular expression. If the regex has a capture group, the first group is returned; otherwise the full match.

extract {
  regex = "id=([a-z0-9-]+)"
}

Field	Type	Required	Description
`regex`	`string`	Yes	Regular expression pattern. Requires decoded text, HTML, or XML body.

Extracts text content from HTML elements matching a CSS selector. Returns an array of matched text strings.

extract {
  css_selector = "h1.title"
}

Field	Type	Required	Description
`css_selector`	`string`	Yes	CSS selector. Requires decoded HTML or text body.

Extracts values from XML using an XPath expression.

extract {
  xpath = "//item/text()"
}

Field	Type	Required	Description
`xpath`	`string`	Yes	XPath expression. Requires decoded XML or text body.

Output Template Variables

The result.output field is a Jinja2 template with access to:

Variable	Description
`args`	The bound argument values passed to the command.
`result`	The decoded (and optionally extracted) response body.
(alias)	Same as `result`, available under the name set by `result_alias`.

secrets.* is not available in result.output. This prevents secrets from leaking through command output.

HCL Functions

Template files support built-in functions for loading external content into string fields.

Function	Description
`file("path")`	Read a file relative to the template directory. Path must be relative and must not contain `..` segments. The file must not resolve outside the template directory.
`base64encode("value")`	Base64-encode a string value (standard encoding).
`trimspace("value")`	Trim leading and trailing whitespace.

Functions can be composed:

sql {
  query = trimspace(file("queries/recent_orders.sql"))
}

Functions work in two forms:

As native HCL expressions: script = file("run.sh")
As string values: script = "file(\"run.sh\")"

Both produce the same result. The native form is preferred.