Skip to content

helix validate

Parse a flow file and check that every workflow loads, every URI's parameters match its component descriptor, and every inline starlang: | block compiles. No engine starts, no consumers bind, no LLM calls fire — this is a pure static check, perfect for CI and pre-commit hooks.

Usage

helix validate <file>

Flags

This subcommand takes no flags. The single positional argument is a flow file (.yaml, .yml, or .json) or a directory of flow files.

Behavior notes

  • Requires $HELIX_LICENSE. Verified at process start.
  • Loads the full definition set via the same loader helix run uses, including imports: and ${file:...} includes. A parse error is rewritten with actionable hints (offending line number, common-mistake callouts for target: vs to:, indentation issues, missing trigger URIs, etc.).
  • Runs two static analyses in addition to the load:
  • URI parameter validation — every workflow trigger and step URI is parsed; query params are cross-checked against the engine.Describable descriptor for the component. Unknown params produce warnings; missing-required or bad-enum produce errors.
  • Starlang block validation — every inline starlang: | block reachable from the entry file (including imports) is statically type-checked. Errors fail the validation; warnings are surfaced but do not block.
  • Prints one line per workflow and per connector: Workflow "X": OK (trigger: Y, steps: N).
  • Warnings are printed first, errors last. The final summary line tells you Validation passed / Validation passed (with warnings) / Validation FAILED.
  • The .env auto-load runs so ${ENV_VAR} references can be resolved.

Exit codes

  • 0 — load + URI check + Starlang check all green (warnings permitted).
  • non-zero — at least one error.

Examples

Validate a flow:

$ helix validate app.yaml
Workflow "ingest": OK (trigger: file://./data, steps: 4)
Workflow "chat-agent": OK (trigger: agui://0.0.0.0:4200/agent, steps: 1)

Validation passed: 2 workflow(s), 0 connector(s), 3 starlang block(s)

Validate a whole project directory:

helix validate .

Use in CI:

helix validate flows/ || exit 1

Source

cmd/helix/main.go lines 1486-1543 (cmdValidate), 1414-1484 (explainValidateError), 1505-1506 (URI + Starlang hooks).

See also