Skip to main content

CLI overview

Pick the command that matches your goal. loom run, loom check, and loom compile accept Loom and GitLab workflow sources. loom config inspects the runtime-only defaults layer that loom run --local can consume.

Install the released binaries​

Follow the canonical release-install procedure. It pins both an immutable release version and the reviewed installer revision for that release. Do not fetch the installer from main, omit the version, or pass latest.

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.

The installer resolves your platform and downloads from the immutable GitLab release contract under /-/releases/<tag>/downloads/.... The canonical procedure also shows how to select only the CLI.

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.

Exact core commands, flags, and defaults​

The generated core CLI command reference is captured from the built loom executable. Use it as the canonical source for root, check, compile, config, run, and version usage, flags, and displayed defaults. The conceptual pages below explain when and why to use each command.

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 runLoom/GitLab source and layered runtime configReceipt + runtime logs
Validate workflow structure before runningloom checkLoom/GitLab source and optional GitLab contextValidation receipt + stderr errors
Inspect the compiled graph or planloom compileLoom/GitLab source and optional GitLab contextGraph IR or plan report JSON
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:

  • selected Loom or GitLab workflow and optional GitLab context
  • 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:

  • selected Loom or GitLab workflow and optional GitLab context

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:

  • selected Loom or GitLab workflow and optional GitLab context

What it prints:

  • Graph IR v1 or value-safe GitLab plan 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​