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

Flag	Type	Default	Description
--workflow	string	.loom/workflow.yml	Path to the workflow YAML file

Exit codes

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

Output streams

Stream	Content
stdout	Graph IR v1 JSON (on success)
stderr	Warnings (non-fatal) and errors (fatal)

Graph IR output format

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

Key	Type	Description
schema	string	IR schema identifier — currently loom.graph-ir.v1
stages	string[]	Ordered list of stage names
nodes	object[]	Executable jobs (template-only jobs are excluded)
edges	object[]	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

Code	Meaning
WF_PLANNER_VARIABLE_NON_SCALAR	A variable value was not a scalar; it was ignored while building the Graph IR
WF_PLANNER_MISSING_NEED	A 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.

Related commands

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

Related

• Workflow schema v1
• Syntax (v1)
• What to share