Skip to main content

loom run

Execute a Loom workflow and produce structured diagnostic artifacts (receipt + runtime logs). Every run — pass or fail — writes a receipt and a log directory so failures are deterministic to triage.

Synopsis​

loom run --local --workflow .loom/workflow.yml

--local is required today. Remote execution is not yet available.

Requirements​

  • --local flag: required for all runs in the current release.
  • Docker: jobs with an image: field run inside Docker. The Docker daemon must be installed and reachable. See Docker provider.
  • Host shell: jobs without image: run directly on your host shell. See Host provider.

Flags​

FlagTypeDefaultDescription
--localboolfalseRun locally (required). Jobs with image: use Docker; jobs without use the host shell
--workflowstring.loom/workflow.ymlPath to the workflow YAML file
--streamboolfalseStream job stdout/stderr to the terminal while executing
--verbose, -vboolfalsePrint additional run metadata to the terminal
--quiet, -qboolfalsePrint only minimal output; rely on receipts and log pointers for details
--cache-diffboolfalseRun twice (cache=off then cache=on) and quarantine cache-hit keys on mechanical divergence
--docker-workspace-mountstringephemeral_volumeDocker workspace mount mode: bind_mount or ephemeral_volume. Overrides LOOM_DOCKER_WORKSPACE_MOUNT

Output verbosity: --quiet, --verbose, --stream​

These flags control terminal output only. Structured runtime logs are always written to .loom/.runtime/logs/<run_id>/ regardless of verbosity settings.

FlagBehavior
(default)Standard output — job started/finished, status, receipt path
--quietMinimal output — receipt path and final status only
--verboseAdditional metadata (useful when you don't want to open runtime logs yet)
--streamStream job stdout/stderr in real time (increases console volume substantially)

Environment variables​

VariableValuesDescription
LOOM_DOCKER_WORKSPACE_MOUNTbind_mount, ephemeral_volumeDocker workspace mount mode. Overridden by --docker-workspace-mount flag

Docker workspace mount resolution order​

  1. --docker-workspace-mount flag value (if set)
  2. LOOM_DOCKER_WORKSPACE_MOUNT environment variable (if set)
  3. Default: ephemeral_volume

Outputs​

Every run produces two artifact types:

ArtifactLocationDescription
Receipt.loom/.runtime/receipts/loom-run-local-<run_id>.jsonStructured run metadata: status, exit code, command, logs pointer
Runtime logs.loom/.runtime/logs/<run_id>/Per-job structured logs, manifests, and event streams
Job artifacts.loom/.runtime/logs/<run_id>/jobs/<job_id>/artifacts/Files extracted from job workspaces when artifacts: is configured

Runtime logs directory structure​

.loom/.runtime/logs/<run_id>/
├── pipeline/
│   ├── summary.json          # Overall pipeline status + exit code
│   └── manifest.json         # Job pointers (find failing job here)
├── jobs/<job_id>/
│   ├── summary.json          # Job-level status
│   ├── manifest.json         # Step pointers (find failing step here)
│   ├── user/script/<NN>/
│   │   ├── summary.json      # Step status
│   │   └── events.jsonl      # Step event stream
│   ├── system/<section>/
│   │   ├── summary.json      # System section status
│   │   └── events.jsonl      # System event stream
│   └── artifacts/            # Extracted job artifacts (when configured)
└── events.jsonl              # Legacy compatibility

Start at pipeline/summary.json, then follow pointers in pipeline/manifest.json to the failing job and step.

Exit codes​

CodeMeaning
0All jobs succeeded
1One or more jobs failed, or the run failed to start

When --cache-diff is used, exit code 1 also indicates mechanical divergence between the cache-off and cache-on runs.

Output streams​

StreamContent
stderrStatus messages, receipt path, loom run passed / error summary
stdout(unused in normal operation)

Example output​

Successful run​

loom run passed
receipt: .loom/.runtime/receipts/loom-run-local-1772050684042246000.json

Failed run​

On failure, the receipt path is printed before the error so you always have a pointer to the full logs:

receipt: .loom/.runtime/receipts/loom-run-local-1772050684042246000.json
loom run: job "build" failed (exit code 2)

Examples​

Run the default workflow​

loom run --local

Run with streaming output​

loom run --local --stream

Run a custom workflow with verbose output​

loom run --local --workflow ci/nightly.yml --verbose

Run with bind mount workspace mounting​

loom run --local --docker-workspace-mount bind_mount

Cache differential analysis​

loom run --local --cache-diff

Runs the workflow twice (first with cache disabled, then with cache enabled) and compares outputs. If the cache-on run produces different results, affected cache keys are quarantined and the run exits non-zero.

Failure triage​

When a run fails, distinguish between two failure types:

Provider / environment failure (Docker unavailable, image pull fails, permission errors):

  1. Open .loom/.runtime/logs/<run_id>/pipeline/summary.json
  2. Follow pointers in pipeline/manifest.json to the failing job
  3. Check jobs/<job_id>/system/<section>/events.jsonl

User step failure (your script: returned non-zero):

  1. Open .loom/.runtime/logs/<run_id>/pipeline/manifest.json
  2. Find the failing job, open jobs/<job_id>/manifest.json
  3. Follow failing_step_events_path to the step's events.jsonl

For the full pointer-first triage flow, see the Diagnostics ladder.

Provider selection​

loom run selects a provider per job based on the workflow definition:

Job has image:ProviderDocumentation
YesDockerDocker provider
NoHost shellHost provider

Workflow-level caching (when configured) is documented at Cache.

  • loom check — validate the workflow schema before running
  • loom compile — inspect the compiled job graph without executing