​Helpers

Kestra provides a set of helper functions designed to make local flow development easier — especially when working with large or modular flows.

Expanding flows before upload

Use the flow validate command to validate and expand your flow locally.
This command will output the expanded version of your flow, resolving any helper references.

./kestra flow validate path-to-your-flow.yaml

[[> file.txt]]: Include external files

When working on large flows, inlining long scripts or SQL statements can make maintenance difficult.
The include helper lets you reference external files inside your flow YAML, keeping it clean and modular.

Example

Without helper

id: include
namespace: company.team

tasks:
  - id: t1
    type: io.kestra.plugin.core.debug.Return
    format: |
      Lorem Ipsum is simply dummy text of the printing
      .....
      500 lines later

With helper

id: include
namespace: company.team

tasks:
  - id: t1
    type: io.kestra.plugin.core.debug.Return
    format: "[[> lorem.txt]]"

Then, create a local file named lorem.txt containing your text.

Supported path formats

When including a file, ensure you use the correct YAML scalar type — literal (quoted or unquoted) for single-line values or folded for multiline content.

Local flow validation

To validate your flow locally (especially if it uses helpers), use the --local flag.
This ensures validation runs with the same plugins as your local environment.

./kestra flow validate --local path-to-your-flow.yaml

Expand includes

To explicitly expand your flow (resolving includes and helpers) without validation, use:

./kestra flow expand path-to-your-flow.yaml

This command outputs a version of your flow ready for upload to the Kestra server.