Reference
Exact command behavior, stable artifact formats, and schema documentation for Loom.
New to Loom? Start with Hello Loom or the Introduction.
Start here if…
| Goal | Entry point |
|---|---|
| Run a workflow locally | loom run |
| Validate workflow structure before running | loom check |
| Generate a compiled representation for inspection | loom compile |
| Inspect the effective layered runtime config | loom config |
| Understand which surface to edit | CLI overview and Runtime config |
| Debug a failing run | Diagnostics ladder, then Runtime logs contract |
| Understand what Loom wrote to disk | Runtime logs contract and Receipts contract |
| Print the CLI version for a bug report | loom version |
CLI
| Command | Purpose |
|---|---|
| CLI overview | Choose the right command and understand which surface each command reads |
loom run | Execute a workflow and produce runtime logs + a run receipt |
loom check | Validate workflow YAML against the schema and Loom's validation rules |
loom compile | Compile a workflow into Graph IR JSON for inspection or tooling |
loom config | Inspect the effective layered runtime config and discover config sources |
loom version | Print the CLI version string |
Use the CLI reference with this boundary in mind:
loom run,loom check, andloom compileoperate on.loom/workflow.ymlloom configinspects layered runtime config for local execution.loom/workflow.ymlremains the executable workflow source of truth
Contracts and schemas
Contracts define the on-disk artifact formats that Loom guarantees. Build tooling against contract fields (pointer fields, schema_version) rather than internal implementation details.
| Contract | What it covers |
|---|---|
| Runtime logs | On-disk log structure, pointer-first navigation (summary → manifest → failing unit events), and the current loom.runtime.logs.v2 schema |
| Receipts | Receipt shape, where receipts are written, and the pointer fields that link to runtime logs |
| Secrets error codes | SECRETS_* error codes, cause matrices, and fix guidance |
| Workflow schema v1 | Authoritative YAML schema for workflows (v1) |
MCP (Cursor / AI agents)
The Loom MCP server exposes the CLI as Model Context Protocol tools for editor-integrated workflows.
| Page | What it covers |
|---|---|
| MCP overview | Setup instructions for Cursor, requirements, and capabilities |
| MCP tools reference | All MCP tools with parameters, outputs, examples, and a step-by-step failure triage flow |
Versioning
Loom uses versioned schemas across multiple surfaces. Each surface is versioned independently.
| Surface | Version field | Current value | Where it appears |
|---|---|---|---|
| Workflow schema | version in workflow YAML | v1 | Syntax v1, Workflow schema v1 |
| Runtime logs | schema_version in every JSON artifact | loom.runtime.logs.v2 | Runtime logs contract |
| Receipts | schema_version in receipt JSON | v1 | Receipts contract |
During Alpha, schemas may evolve between releases. The schema_version field will be incremented on breaking changes. No formal backward compatibility window is guaranteed yet.
Troubleshooting
| Page | When to use it |
|---|---|
| Diagnostics ladder | Step-by-step failure triage using pointer navigation |
| Common failures | Recognize common failure patterns and take the first fix step |
| What to share | Prepare a minimal report when asking for help |