loom check
Validate a workflow file against the Loom schema v1 and emit a receipt. Use loom check as a fast pre-flight gate before loom run — it catches structural errors without executing any jobs.
Synopsis
loom check
loom check accepts no flags. It always validates the workflow at .loom/workflow.yml (located via repo-root discovery).
Flags
None. The workflow path is not configurable — loom check always targets .loom/workflow.yml.
To validate a workflow at a different path, use loom compile --workflow <path> for structural verification, though loom check remains the canonical schema validator.
Outputs
| Artifact | Location | Description |
|---|---|---|
| Receipt | .loom/.runtime/receipts/<timestamp>-check-<pid>.json | Structured result with schema version, status, and any errors |
| Schema errors | stderr | Human-readable error lines on validation failure |
Exit codes
| Code | Meaning |
|---|---|
0 | Schema is valid |
1 | Schema is invalid, or the command failed (e.g. could not locate the repo root or write the receipt) |
Output streams
All output goes to stderr — stdout is not used.
| Stream | Content |
|---|---|
| stderr | loom check passed / schema error lines, receipt path, final status line |
| stdout | (unused) |
Example output
Success
loom check passed
receipt: .loom/.runtime/receipts/20260304T183012Z-check-48291.json
Failure
workflow.yml:12 missing required key "stage" in job "build"
workflow.yml:18 expected sequence for "script", got string
receipt: .loom/.runtime/receipts/20260304T183012Z-check-48291.json
loom check failed (exit code 1)
Receipt structure
The receipt JSON captures the validation result so downstream tools can parse it programmatically.
{
"schema_version": "v1",
"kind": "loom-check",
"loom_version": "0.4.2",
"command": ["loom", "check"],
"exit_code": 0,
"status": "success",
"workflow_schema_v1": {
"workflow_path": "/repo/.loom/workflow.yml",
"valid": true,
"errors": []
}
}
On failure, exit_code is 1, status is "failure", workflow_schema_v1.valid is false, and workflow_schema_v1.errors contains structured error entries.
Common schema errors
| Error | Symptom | Fix |
|---|---|---|
| Missing required keys | Errors about missing version, stages, job stage, target, or script | Compare against Syntax (v1) and add the missing keys |
| Type mismatch | expected mapping / expected sequence | Check YAML types — script must be a list of strings, stages must be a list |
| Invalid include path | Errors resolving include.local templates | Ensure includes live under .loom/templates/ with no .. traversal (see Syntax (v1) → include) |
| Cache shape errors | Errors about cache.paths, cache.key, or multi-cache fields | Cross-check Cache and Syntax (v1) → cache |
When reporting a schema validation failure, share the receipt path and a small excerpt. See What to share.
Related commands
loom compile— resolve includes/templates and inspect the compiled graphloom run— execute the workflow after validation passes