# 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`](https://hub.aux4.io) 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.

```bash
> aux4 aux4 pkger install aux4/render
```

```json
...
  {
    "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

```bash
> 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:

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

---

## See Also

- [Executors](/executors)
- [Variables](/variables)
- [Commands](/commands)
- [Hooks](/hooks)