Skip to main content

Hello Loom

Create and run a small workflow, inspect its artifacts, then change one command to practice diagnosing a failure.

Install Loom​

Follow the canonical release-install procedure. Choose an immutable release version and its matching reviewed installer revision. Do not fetch the installer from main, omit the version, or pass latest.

The default installer downloads both loom and loom-mcp from the canonical GitLab release URLs and installs them into ~/.local/bin.

This guide uses loom. If ~/.local/bin is not already on your PATH, follow the script's printed PATH guidance and then verify your install:

loom version

Prerequisites​

  • A current Loom CLI and a running Docker daemon.
  • A Git repository with a committed HEAD. Loom snapshots it before execution.

1) Create a small Docker workflow​

Save .loom/workflow.yml in the repository root:

version: v1
stages: [ci]

hello:
  stage: ci
  target: linux
  image: alpine:3.22
  script:
    - echo "hello from Docker"

2) Validate and run​

loom check
loom compile --workflow .loom/workflow.yml
loom run --workflow .loom/workflow.yml --stream

The run prints its directory, state path and event path. A successful run exits zero and prints loom run passed.

.loom/.runtime/runs/<run_id>/state.jsonl
.loom/.runtime/runs/<run_id>/events.jsonl

state.jsonl records workflow, job, step and command transitions. events.jsonl contains execution output and diagnostics with timestamps and identifiers. Known secrets are masked before recording. Declared artifacts are stored separately.

3) Read the saved run​

Use the printed directory name as <run_id>:

loom logs <run_id> --state
loom logs <run_id> --tail 30
loom logs <run_id> --json

The final workflow state records status: "success" and exit_code: 0. These commands also work after the execution process exits. MCP clients can use loom_read_run and loom_read_events for the same files.

4) Diagnose an intentional failure​

Replace the script with a failing command and run again:

script:
  - echo "before failure"
  - exit 7
loom run --workflow .loom/workflow.yml
loom logs <new_run_id> --state
loom logs <new_run_id> --tail 30

The invocation fails. State identifies the failed command and exit code 7; events retain its preceding output. There are no manifests or nested log paths to follow. If setup fails before recording begins, use the terminal error.

Troubleshooting and next steps​

If Docker jobs cannot start, verify docker info and image access. If Loom cannot resolve HEAD, commit a project file and retry from the repository root.

See Runtime logs, the Diagnostics ladder, Docker provider and workflow syntax.