---
url: https://listr2.kilic.dev/task/output.md
---

# {{ $frontmatter.title }}

*Task* can push output while running for informing the user of what is going on or programmatically for more information about an underlying task.

::: info Example

You can find the related examples [here](https://github.com/listr2/listr2/tree/master/examples/task-output.example.ts).

:::

## Usage

Depending on the renderer selected, the format of the output will change. For *DefaultRenderer* everything will be rendered in a small bar just after the task, while for *SimpleRenderer*, *VerboseRenderer*, or *TestRenderer* it will be more like a logger. You can find the individual properties for *Task* `output` behavior in the next section.

### Show Output Through the Task Itself

This will show the output in a small bar that can only show the last output from the task.

<<< @../../examples/docs/task/output/with-task.ts{8,11,14}

### Passing Data Through an Observable or a Stream

Since observables and streams are supported they can also be used to generate output.

::: details  Code Example — Stream

<<< @../../examples/docs/task/output/stream.ts

:::

::: details  Code Example — Observable

<<< @../../examples/docs/task/output/observable.ts

:::

### Reset the Output&#x20;

Setting the output to `null` clears whatever the *Task* has already streamed instead of rendering anything new.

```typescript
task.output = 'I will push an output.'

task.output = null
```

For *DefaultRenderer* this empties the output bar and the bottom bar for that *Task*, so a following `{ persistentOutput: true }` finalize keeps nothing. The append-only loggers, *SimpleRenderer*, *VerboseRenderer*, and *TestRenderer*, ignore it since their history can not be cleared.

::: warning

Prior to this, `task.output = null` used to render the literal string `"null"`.

:::

## Render a WritableStream Directly

`process.stdout` and `process.stderr` might get hooked depending on the usage of *ProcessOutput* on the selected renderer. So anything that requires a `WritableStream` while the task is running to dump the output should go through `task.stdout()`, which creates a temporary `WritableStream` for the task, instead of writing to the stream directly.

## Render Output of a Command

Task output can be piped to the `task.stdout()` directly since it is a `WritableStream`, whenever you are running something that writes to the `process.output`. This usually can be utilized to show the outputs of the commands.

::: details  Code Example

<<< @../../examples/docs/task/output/pass-stdout.ts

:::

Whenever more control over the stream is required, temporary `WritableStream` can be created through helper function `createWritable` via passing it a callback to dictate the behavior of the `write` call.

::: details  Code Example

<<< @../../examples/docs/task/output/pass-stdout-with-control.ts

:::

## Renderer

### *DefaultRenderer*

#### Use the Output Bar&#x20;

For *DefaultRenderer*, if the task has a title, last line of output will be rendered under the task title by default.

Item count that is desired to be showed in the output bar can be set through the renderer option `outputBar` and is per-task.

* `true` only keep the last line.
* `Infinity` will keep all the lines.
* `number` will keep the defined amount of lines.
* `false` will not render output with this method.

::: details  Code Example

<<< @../../examples/docs/task/output/renderer-default-outputbar.ts

:::

#### Use the Bottom Bar

For *DefaultRenderer*, data can be outputted to a bar below all the render area, this is useful for fast moving logs. If the task has no title, last line of output will be rendered in the bottom bar by default.

Bottom bar can be selected through *Task* renderer options, where it will create a bar at the end of the tasks leaving one line return space in between.

Item count that is desired to be showed in the bottom bar can be set through the renderer option `bottomBar` and is per-task.

* `true` only keep the last line.
* `Infinity` will keep all the lines.
* `number` will keep the defined amount of lines.
* `false` will not render output with this method.

::: details  Code Example

<<< @../../examples/docs/task/output/renderer-default-bottombar.ts

:::

#### Persistent Output

To keep the output after the task has been completed while using the default renderer, you can set `{ persistentOutput: true }` in the *Task* or *Listr* renderer options.

::: details  Code Example

<<< @../../examples/docs/task/output/renderer-default-persistent.ts

:::

### *SimpleRenderer* & *VerboseRenderer*

The non-TTY renderers have no bars. Every line written to `task.output` is logged as an `OUTPUT` entry as it arrives, interleaved with the rest of the log, so the output is inherently persistent — the `outputBar`, `bottomBar` and `persistentOutput` options do not apply.