> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For full documentation content, see https://platform.bctrl.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Output Formatting

> Format BCTRL CLI output with JSON field projection, jq expressions, and Handlebars templates.

Most data commands take three flags for shaping output, meant for scripts and coding agents:

```bash
--json [fields]
--jq <expression>
--template <template>
```

## JSON

`--json` prints the raw response:

```bash
bctrl runtime list --json
```

Add a comma-separated field list to keep only those keys:

```bash
bctrl runtime list --json id,status
```

On a list response, the projection applies to each object inside `data`.

## jq

`--jq` filters the JSON with a jq expression and requires `--json`:

```bash
bctrl runtime list --json --jq '.data[].id'
```

The CLI bundles `jq`, so this flag works without a system `jq` installed.

## Templates

`--template` formats the JSON with a Handlebars template and also requires `--json`:

```bash
bctrl runtime list \
  --json \
  --template '{{#each data}}{{id}} {{status}}{{newline}}{{/each}}'
```

A few extra helpers cover common formatting needs:

| Helper           | Purpose                 |
| ---------------- | ----------------------- |
| `{{json value}}` | Render a value as JSON. |
| `{{newline}}`    | Render a newline.       |
| `{{tab}}`        | Render a tab.           |

## Rules

Because `--jq` and `--template` operate on the JSON response, passing either without `--json` is an error:

```bash
bctrl runtime list --jq '.data'
# error: cannot use --jq without specifying --json
```

Build scripts on JSON output. The human-oriented terminal text can change between releases, so do not parse it.