Transformers

Transformers let you parse raw command output into structured data before returning it to the caller. Without a transformer, output streams line-by-line as raw text.

Behavior

• Without transformer: Output streams in real-time, line by line (SSE output events).
• With transformer: Output is buffered, transformed, then sent as a single transformed_output event.

Types

text

Returns the raw output as a single string. Useful when you want buffered output instead of streaming.

transformer:
  type: text

json

Parses the output as JSON. Falls back to a string if parsing fails.

transformer:
  type: json

Example: A command that outputs {"cpu": 45, "mem": 72} returns that as a parsed JSON object.

lines

Splits output by a separator into an array. Empty lines are filtered out.

transformer:
  type: lines
  separator: "\n"    # default

Example: df -h output becomes an array of lines:

["Filesystem  Size  Used Avail Use% Mounted on", "/dev/sda1  50G  20G  28G  42% /", ...]

regex

Extracts fields from each line using regex capture groups.

transformer:
  type: regex
  pattern: "(\\S+)\\s+(\\d+)\\s+(\\S+)\\s+(\\S+)"
  fields:
    - user
    - pid
    - cpu
    - mem

Each capture group maps to a field name. Returns an array of objects:

[
  {"user": "root", "pid": "1", "cpu": "0.0", "mem": "0.1"},
  {"user": "www", "pid": "1234", "cpu": "2.3", "mem": "1.5"}
]

Response format

When using a transformer, the API returns a transformed_output event (SSE) or a data field (JSON):

SSE:

data: {"type":"transformed_output","data":[...]}
data: {"type":"done","exit_code":0}

JSON (with Accept: application/json):

{
  "data": [...],
  "exit_code": 0
}

Without a transformer, you get output events or an output string field instead.