loom check
Validate a Loom or GitLab workflow and emit a receipt without executing jobs.
Canonical command usage
Use the
generated core CLI command reference for the exact
loom check synopsis, flags, and displayed defaults.
Workflow source and context
Without flags, Loom selects .loom/workflow.yml before the repository root
.gitlab-ci.yml. --format loom|gitlab selects exactly one parser; read or
parser errors never fall back to the other format. --workflow accepts a
project-relative trusted path. An exact .gitlab-ci.yml basename is inferred as
GitLab, while other custom GitLab filenames require --format gitlab.
--context accepts a project-relative JSON file with schema
loom.gitlab-pipeline-context.v1. Its variables and changes drive GitLab
rules and expansion. runner_tags describes local runner capabilities used to
satisfy or report plan requirements; it is not job-selection data. Ambient CI
variables and runtime settings are ignored. Context files are limited to 1 MiB.
Outputs
| Artifact | Location | Description |
|---|---|---|
| Receipt | .loom/.runtime/receipts/<timestamp>-check-<pid>.json | Structured result, selected source, safe GitLab plan facts, and errors |
| Schema errors | stderr | Human-readable error lines on validation failure |
Exit codes
| Code | Meaning |
|---|---|
0 | Loom source is valid, GitLab plan is executable, or GitLab workflow is skipped |
1 | Source is invalid, GitLab plan is non-executable, or the command fails |
Output streams
All output goes to stderr — stdout is not used.
| Stream | Content |
|---|---|
| stderr | loom check passed or loom check skipped, diagnostic lines, and receipt path |
| 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": []
}
}
GitLab receipts replace workflow_schema_v1 with source and gitlab_plan.
The plan projection includes state, selection identity, selection records,
requirements, and diagnostics without scripts or resolved context values.
workflow_skipped records status skipped and exits 0. source_invalid and
non_executable record status failure and exit nonzero.
GitLab validation reports missing runner tags, privileged services, hosted macOS, OIDC tokens, Pages, and environments as requirements. Check never grants privileged-service consent. Optional manual jobs remain visible but are not executed. Report processing and artifact expiry are reported limitations.
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