Skip to main content

loom compile

Compile a workflow into Graph IR v1 JSON. Use loom compile to inspect what Loom "sees" after resolving includes, templates, and extends — without executing anything.

Synopsis​

loom compile --workflow .loom/workflow.yml

Use cases​

  • Diff compiled plans across branches or commits to spot unexpected job changes
  • Verify include/template resolution — confirm extends and include.local merge correctly
  • Inspect the job graph (nodes + needs edges) before running
  • Feed Graph IR to external tools for visualization or analysis

Flags​

FlagTypeDefaultDescription
--workflowstring.loom/workflow.ymlPath to the workflow YAML file

Exit codes​

CodeMeaning
0Compilation succeeded (Graph IR written to stdout)
1Compilation failed (error written to stderr)

Output streams​

StreamContent
stdoutGraph IR v1 JSON (on success)
stderrWarnings (non-fatal) and errors (fatal)

Graph IR output format​

loom compile outputs a JSON object with these top-level keys:

KeyTypeDescription
schemastringIR schema identifier — currently loom.graph-ir.v1
stagesstring[]Ordered list of stage names
nodesobject[]Executable jobs (template-only jobs are excluded)
edgesobject[]Dependency edges (currently: needs relationships)

Example output​

{
  "schema": "loom.graph-ir.v1",
  "stages": ["ci"],
  "nodes": [
    {
      "id": "check",
      "stage": "ci",
      "target": "linux",
      "image": "alpine:3.20",
      "script": ["pnpm i --frozen-lockfile", "task check"],
      "variables": [{ "key": "PNPM_STORE_DIR", "value": ".pnpm-store" }],
      "cache": {
        "paths": [".pnpm-store", ".nx/cache"],
        "policy": "pull-push",
        "when": "always",
        "key": { "prefix": "loom-cache", "files": ["pnpm-lock.yaml"] }
      }
    }
  ],
  "edges": []
}

Notes on node fields:

  • image, variables, and cache are omitted when not present or not effective for a node.
  • cache can be a single object or a list, matching the workflow's single-cache vs. multi-cache shape.

Warnings​

Warnings are non-fatal. They are written to stderr in this format:

warning: <code> <path> <message>

Known warning codes​

CodeMeaning
WF_PLANNER_VARIABLE_NON_SCALARA variable value was not a scalar; it was ignored while building the Graph IR
WF_PLANNER_MISSING_NEEDA needs entry referenced a non-existent executable node; the edge was ignored

This list may grow. If you see an unknown warning code, include it when reporting issues.

Examples​

Compile the default workflow​

loom compile

Compile a workflow at a custom path​

loom compile --workflow ci/staging-workflow.yml

Pipe Graph IR to jq for inspection​

loom compile | jq '.nodes[] | {id, stage, image}'

Diff compiled plans between branches​

diff <(git stash && loom compile) <(git stash pop && loom compile)

Reporting issues​

When loom compile fails or emits unexpected warnings, include:

  1. The command you ran (including --workflow if used)
  2. Warning or error lines from stderr
  3. The first ~20 lines of JSON output (redacted if needed)

See What to share for the full checklist.

  • loom check — validate schema without compiling
  • loom run — execute the compiled workflow