Foundry
Home CLI Command

gxwf validate

Validate Galaxy workflow structure, tool state, and optional connection compatibility before runtime execution.

draft cli-commandcli/gxwf
Revised
2026-05-06
Rev
3
cli gxwf validate @galaxy-tool-util/cli @ 1.4.0 upstream ↗

gxwf validate

Validate Galaxy workflow files (structure + optional tool state)

gxwf validate [options] <file>

Arguments

name req variadic description
file ✓ Workflow file (.ga, .gxwf.yml)

Options

flag arg description
--format <fmt> <fmt> Force format: native or format2 (auto-detected by default)
--no-tool-state Skip tool state validation negatable
--cache-dir <dir> <dir> Tool cache directory
--mode <mode> <mode> Validation backend: effect (default) or json-schema default: "effect"
--tool-schema-dir <dir> <dir> Directory of pre-exported per-tool JSON Schemas (for offline json-schema mode)
--json Output structured JSON report
--report-html [file] [file] Write HTML report to file (or stdout if omitted)
--connections Validate connection-type compatibility (collection algebra, map-over)
--strict Shorthand for --strict-structure --strict-encoding --strict-state
--strict-structure Reject unknown keys at envelope/step level
--strict-encoding Reject JSON-string tool_state and format2 field misuse
--strict-state Require every tool step to validate; no skips allowed

gxwf validate

Validate a Galaxy workflow source file before attempting runtime execution. Use this as the design-time guardrail after step implementation and again after final workflow assembly.

Output

Default output is human-readable diagnostics. JSON output should be treated as the preferred cast-skill interface; free-text diagnostics are a fallback for humans.

Examples

gxwf validate workflow.ga
gxwf validate workflow.gxwf.yml --json
gxwf validate workflow.gxwf.yml --json --connections --strict
gxwf validate workflow.ga --mode json-schema --tool-schema-dir ./tool-schemas --json

Gotchas

  • Validation is design-time structure checking. It does not prove that a workflow test will pass under Planemo.
  • Run after each generated Galaxy step when the harness can still attribute failures to the fresh step.
  • Run again after assembly to catch cross-step or workflow-level issues before runtime testing.
  • Prefer --json whenever a cast skill or harness needs to classify diagnostics.
  • Use --connections when tool cache metadata is available and data-shape compatibility matters, especially around collections and map-over.
  • --no-tool-state weakens validation. If used, record why tool metadata was unavailable and rerun without it before final runtime testing.