How Loom works in practice
This guide is for people already past the landing page and quickstart. It explains the operator loop behind Loom so you know which command to run, which artifact to inspect, and where to go next when a run fails.
Command to artifact map
| Command | What it gives you | Next file or page to inspect |
|---|---|---|
loom check | Schema validation result plus a receipt | Fix schema issues, or continue to loom compile |
loom compile --workflow .loom/workflow.yml | Resolved Graph IR | Confirm the plan before you execute |
loom run --local --workflow .loom/workflow.yml | State and execution events | Run loom logs <run_id> --state, then read events |
| Failing run triage | State and event inspection | Diagnostics ladder |
The four-step loop
| Step | What you do | What Loom does |
|---|---|---|
| 1. Author | Write .loom/workflow.yml | — |
| 2. Validate | Run loom check | Validates against schema v1, resolves includes, emits a receipt |
| 3. Run | Run loom run --local --workflow .loom/workflow.yml | Executes jobs (host or Docker), writes state.jsonl + events.jsonl |
| 4. Diagnose | Read workflow state, then contextual events | Identifiers locate the failed command and its output |
Common failure branches
Use these as your first branch instead of reading everything top to bottom.
Schema or authoring failure
Symptom: loom check fails before execution starts.
What to inspect next: the validator error output and Syntax v1.
Runtime failure in a user step
Symptom: loom run --local starts, but a pipeline or job ends in failure.
What to inspect next: Diagnostics ladder, starting from the announced run directory.
Provider or environment failure
Symptom: missing tools, Docker startup issues, permissions problems, or host/container drift.
What to inspect next: Providers overview, Common failures, then the recorded diagnostics.
What the workflow loop produces
Recorded runs write state.jsonl and events.jsonl under
.loom/.runtime/runs/<run_id>/. State follows workflow, job, step and command
transitions. Events retain contextual messages and stdout/stderr. Declared
artifact bodies are separate under .loom/.runtime/artifacts/<run_id>/.
See Runtime logs,
loom logs and the
Diagnostics ladder.
Next steps
| Goal | Link |
|---|---|
| Run your first workflow end to end | Hello Loom |
| Practice saved-run diagnosis | Diagnostics ladder |
| Learn the full workflow syntax | Syntax v1 |
| Explore the CLI surface | CLI overview |