Skip to main content

CLI overview

Pick the command that matches your goal. loom run, loom check, and loom compile operate on .loom/workflow.yml. loom config inspects the runtime-only defaults layer that loom run --local can consume.

Install the released binaries​

Install the latest release:

curl -fsSL https://gitlab.com/beepbeepgo/loom-build/loom/-/raw/main/install-loom.sh | bash

By default, the installer downloads both loom and loom-mcp from the canonical repository at https://gitlab.com/beepbeepgo/loom-build/loom and installs them into ~/.local/bin.

Common variants:

  • Pin a release: curl -fsSL https://gitlab.com/beepbeepgo/loom-build/loom/-/raw/main/install-loom.sh | bash -s -- v1.2.3
  • Install only the CLI: curl -fsSL https://gitlab.com/beepbeepgo/loom-build/loom/-/raw/main/install-loom.sh | bash -s -- latest loom

The installer resolves your platform and downloads from the stable GitLab release contract under /-/releases/<tag>/downloads/... for pinned versions and /-/releases/permalink/latest/downloads/... for the latest release.

Quick start​

If you're new to Loom, begin with Hello Loom. When something fails, follow the pointer-first flow in the Diagnostics ladder.

Examples in this documentation use the release-installed loom binary.

Contributor note: if you're working from a source checkout, the repo-local ./bin/loom path is a development convenience, not the primary install path for end users.

Alpha 1 constraints:

  • Local execution only: use loom run --local
  • Workflow target: is Linux-only in the current release

Choose a command by intent​

If you want to...Use...Reads...Main output
Run a workflow locallyloom run.loom/workflow.yml and layered runtime configReceipt + runtime logs
Validate workflow structure before runningloom check.loom/workflow.ymlValidation receipt + stderr errors
Inspect the compiled graphloom compile.loom/workflow.ymlGraph IR JSON to stdout
Inspect effective runtime defaultsloom configLayered runtime configCommand help or effective config YAML
Confirm the installed versionloom versionBuild metadataVersion string to stdout

Command groups​

loom run​

Use loom run --local when you want to execute jobs and capture diagnostic artifacts.

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

What it reads:

  • .loom/workflow.yml
  • layered runtime config for local runtime defaults

What it writes:

  • run receipts under .loom/.runtime/receipts/
  • runtime logs under .loom/.runtime/logs/<run_id>/

Next: Diagnostics ladder and Providers overview

loom check​

Use loom check when you want fast schema validation without executing anything.

loom check

What it reads:

  • .loom/workflow.yml

What it does not read:

  • layered runtime config from .loom/config.yml or ~/.config/loom/config.yml

Next: Syntax (v1) and Hello Loom

loom compile​

Use loom compile when you want the resolved job graph after includes, templates, and extends are applied.

loom compile --workflow .loom/workflow.yml

What it reads:

  • .loom/workflow.yml

What it prints:

  • Graph IR v1 JSON to stdout
  • warnings to stderr

Next: Workflow schema v1 and Syntax (v1)

loom config​

Use loom config when you want to inspect the runtime-only defaults layer before you run locally.

loom config show

What it reads:

  • built-in defaults
  • ~/.config/loom/config.yml when present
  • .loom/config.yml when present
  • supported env overlays such as LOOM_DOCKER_WORKSPACE_MOUNT and LOOM_KEEPASS_DB_*

What it does not change:

  • .loom/workflow.yml
  • what loom check reads
  • what loom compile reads

Next: loom config reference and Runtime config

loom version​

Use loom version when reporting issues or verifying your install.

loom version

What it prints:

  • version string to stdout

Common decision points​

  • If you are deciding what the pipeline does, edit .loom/workflow.yml.
  • If you are deciding what defaults Loom should assume before loom run --local starts, use runtime config.
  • If you need a one-off override or a secret value, use environment variables.

Troubleshooting​