Render

Commands can declare a render field to post-process the captured response through an external command via stdin. This is useful for formatting raw JSON output as a list, table, or other human-friendly view — while still letting scripts get the raw data back untouched.

The render command can be anything that reads stdin — cat, jq, tr, a one-off script, aux4 2table, whatever fits. You don't need a special package to use this feature.

The aux4/render package is an optional add-on that makes it more convenient: it reads a JSON array (or object) from stdin and renders it as a list, table, CSV, key/value dump, or YAML, so a command that returns JSON can pipe straight through it instead of hand-rolling formatting logic.

> aux4 aux4 pkger install aux4/render

...
  {
    "name": "list-servers",
    "execute": [
      "json:curl -s api.example.com/servers"
    ],
    "render": {
      "tty": "aux4 render list --primary name --icon \"status[ONLINE:🟢,OFFLINE:🔴,DEGRADED:🟡]\" --secondary region --badge status",
      "table": "aux4 render table name,region,status"
    },
    ...
  }
...

tty — the render command that runs automatically when stdout is a TTY and no --render flag is provided
All other keys are render format names selected explicitly via --render

Selecting a Format

> aux4 list-servers                  # TTY → uses "tty" render (a nicely formatted list)
> aux4 list-servers --render table   # explicit format → aux4 render table
> aux4 list-servers --render none    # raw response output, no rendering
> aux4 list-servers | jq .           # piped output skips rendering automatically

TTY Auto-Detection

When stdout is a TTY and no --render flag is provided, the tty render command runs automatically. When stdout is not a TTY (piped or redirected), rendering is skipped and the raw response is printed. This means aux4 list-servers | jq . works without needing --render none. An explicit --render <name> overrides TTY detection.

Output Capture is Automatic

When a command declares a render field, its execute steps never stream their output directly to the terminal — output is always captured silently into response, regardless of which executor is used (a plain shell command, stdin:, json:, or nout: all behave the same way). Only the render step's own output is ever shown: the rendered result, or the raw response once via --render none / non-TTY passthrough.

The log: executor is an exception — it prints its text directly to stdout in addition to setting response, so it isn't suitable for use with render. The alias: executor shares the terminal's stdio and doesn't capture response at all, so it can't be rendered either.

Parameter Injection in Render

Render commands support ${variable} parameter injection:

...
  {
    "render": {
      "tty": "aux4 render table ${columns}",
      "csv": "aux4 render csv ${columns}"
    }
  }
...

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Render

Selecting a Format

TTY Auto-Detection

Output Capture is Automatic

Parameter Injection in Render

See Also