Template Schema

version    = 1
provider   = "github"
categories = ["scm", "issues"]

environments { ... }   # optional

command "name" { ... } # one or more

command "search_repos" {
  title       = "Search repositories"
  summary     = "Search GitHub repos by query"
  description = "..."

  categories = ["search"]

  annotations { ... }

  param "query" { ... }

  operation { ... }

  result { ... }

  environment_overrides { ... }
}

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

param "per_page" {
  type        = "integer"
  required    = false
  default     = 30
  description = "Results per page (max 100)"
}

url = "https://api.github.com/repos/{{ args.owner }}/{{ args.repo }}"

operation {
  protocol = "http"
  method   = "GET"          # GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
  url      = "https://api.example.com/items/{{ args.id }}"
  path     = "/v2/items"    # optional; appended to url
  stream   = false

  headers = { Accept = "application/json" }
  query   = { filter = "{{ args.filter }}" }
  cookies = { session = "{{ args.session }}" }

  auth { ... }

  body { ... }

  transport { ... }
}

operation {
  protocol = "graphql"
  url      = "https://api.github.com/graphql"

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

  graphql {
    query = <<-GQL
      query($owner: String!, $repo: String!) {
        repository(owner: $owner, name: $repo) {
          stargazerCount
        }
      }
    GQL
    operation_name = "MyQuery"  # optional
    variables = {
      owner = "{{ args.owner }}"
      repo  = "{{ args.repo }}"
    }
  }

  transport { ... }
}

operation {
  protocol = "grpc"
  url      = "https://grpc.example.com"

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

  grpc {
    service             = "example.v1.ExampleService"
    method              = "GetItem"
    descriptor_set_file = "example.pb"  # optional
    body = {
      id = "{{ args.id }}"
    }
  }

  transport { ... }
}

operation {
  protocol = "bash"

  bash {
    script = <<-SH
      jq -r '.[] | .name' {{ args.input_file }}
    SH
    env = {
      MY_VAR = "{{ args.value }}"
    }
    cwd = "/tmp"
    sandbox {
      network          = false
      max_time_ms      = 30000
      max_output_bytes = 1048576
    }
  }

  stream = false
}

operation {
  protocol = "sql"

  sql {
    connection_secret = "myapp.db_url"
    query             = "SELECT id, name FROM users WHERE status = $1 LIMIT $2"
    params            = ["{{ args.status }}", "{{ args.limit }}"]
    sandbox {
      read_only    = true
      max_rows     = 100
      max_time_ms  = 5000
    }
  }
}

operation {
  protocol = "browser"

  browser {
    session_id            = "{{ args.session_id }}"
    headless              = true
    timeout_ms            = 30000
    on_failure_screenshot = true
    steps = [
      { action = "navigate", url = "{{ args.url }}" },
      { action = "snapshot" },
    ]
  }
}

body {
  kind  = "json"
  value = {
    name  = "{{ args.name }}"
    count = "{{ args.count }}"
  }
}

body {
  kind   = "form_urlencoded"
  fields = {
    username = "{{ args.username }}"
    password = "{{ args.password }}"
  }
}

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

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

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

body {
  kind         = "file_stream"
  path         = "{{ args.file_path }}"
  content_type = "application/pdf"
}

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

auth {
  kind     = "api_key"
  secret   = "provider.api_key"
  location = "header"    # header, query, or cookie
  name     = "X-Api-Key"
}

auth {
  kind            = "basic"
  username        = "{{ secrets.jira_email }}"
  password_secret = "provider.password"
}

auth {
  kind    = "o_auth2_profile"
  profile = "myprofile"
}

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

# JSON Pointer (RFC 6901)
extract = { json_pointer = "/data/users" }

# Regular expression — result is the first capture group
extract = { regex = "token=([A-Za-z0-9]+)" }

# XPath — for XML responses
extract = { xpath = "//user/name/text()" }

# CSS selector — for HTML responses
extract = { css_selector = "h1.title" }

transport {
  timeout_ms        = 30000
  max_response_bytes = 8388608

  redirects {
    follow   = true
    max_hops = 5
  }

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

  compression = true

  tls {
    min_version = "1.2"  # 1.0, 1.1, 1.2, or 1.3
  }

  proxy_profile = "corporate"
}

environment_overrides {
  staging {
    operation {
      protocol = "http"
      method   = "GET"
      url      = "https://staging.example.internal/api/items"
      auth {
        kind   = "bearer"
        secret = "myapp.staging_token"
      }
    }

    result {
      decode = "json"
      output = "[staging] {{ result | length }} items"
    }
  }
}

environments {
  default = "production"
  secrets = ["myapp.prod_token"]
  production {
    base_url = "https://api.myapp.com"
  }
  staging {
    base_url = "https://staging.myapp.com"
  }
}