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 |
| Authorize this CLI account | loom auth account |
| Authorize the configured project for ingestion | loom auth project |
| Connect this repository to a Web project | loom web setup project |
| 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 record state and events in two JSONL files |
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 auth account | Authorize scoped account access and manage this device login |
loom auth project | Approve a narrow project credential without storing an account grant |
loom web setup project | Select or create the repository's Web destination |
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 describe recorded fields and behavior. Build tooling against the documented records and command surfaces.
| Contract | What it covers |
|---|---|
| Runtime logs | Workflow state and contextual event JSONL files |
| Receipts | Validation and historical saved-upload receipts |
| Secrets error codes | SECRETS_* error codes, cause matrices, and fix guidance |
| Workflow schema v1 | Authoritative YAML schema for workflows (v1) |
| GitLab pipeline context | The loom.gitlab-pipeline-context.v1 file behind --context: variables, changes, runner_tags, and validation codes |
| GitLab keyword compatibility | Generated matrix of root, job, default: and rules: keywords, rule grammar, and every GL_* code with its fix hint |
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 | JSONL record fields | Unversioned | Runtime logs contract |
| Receipts | schema_version in receipt JSON | v1 | Receipts contract |
| GitLab context | version in the context JSON | loom.gitlab-pipeline-context.v1 | GitLab pipeline context |
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 |