Foundry
Home CLI Command

gxwf convert

Convert a Galaxy workflow between native (.ga) and format2 (.gxwf.yml) representations.

draft cli/gxwf
Revised
2026-09-26
Rev
3
cli gxwf convert @galaxy-tool-util/cli @ 1.10.0 upstream ↗

gxwf convert

Convert between native (.ga) and format2 (.gxwf.yml) formats

gxwf convert [options] <file>

Arguments

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

Options

flag arg description
--to <format> <format> Target format: native or format2 (infers opposite by default)
--output <file> <file> Write result to file (default: stdout)
--compact Omit position info in format2 output
--json Force JSON output
--yaml Force YAML output
--format <fmt> <fmt> Force source format (auto-detected by default)
--stateful Use cached tool definitions for schema-aware state re-encoding
--cache-dir <dir> <dir> Tool cache directory (for --stateful)
--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 convert

Convert a Galaxy workflow between the native .ga JSON and the .gxwf.yml format2 representation. Use this to normalize fetched IWC workflows into a consistent comparison representation.

Output

Default output is the converted workflow on stdout. With --output, the result is written to a file. JSON output is selected with --json (or --to native); YAML output is selected with --yaml (or --to format2).

Examples

gxwf convert workflow.ga --to format2 --output workflow.gxwf.yml
gxwf convert workflow.ga --to format2 --compact
gxwf convert workflow.gxwf.yml --to native --output workflow.ga

Gotchas

  • Default output is stdout; pipe or pass --output when persisting.
  • --compact drops node position metadata; useful for structural diffs and skeleton generation.
  • With a populated tool cache, conversion re-encodes tool state using cached definitions by default. Use --no-stateful to copy tool state through verbatim, or --stateful to force re-encoding even when the cache is empty. See galaxy-tool-cache.
  • Version 1.13.1 preserves numeric input min and max as native Galaxy range validators and recovers them on export.