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. Choose an immutable release version and its matching reviewed installer revision. 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 core CLI command reference lists root, artifacts, check, compile, config, context, logs, run, runs, 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: jobs run through Docker or the host shell on this machine
  • Native host jobs require target: linux on Linux or target: darwin on macOS; Docker jobs require target: linux

Choose a command by intent​

If you want to...Use...Reads...Main output
Run a workflow locallyloom runLoom/GitLab source and layered runtime configWorkflow state + events
Inspect declared job outputsloom artifactsPublished job archivesBounded member/body JSON
Find saved workflow runsloom runsRecorded workflow state filesOrdered run summaries
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
Generate a GitLab pipeline contextloom contextCurrent git branch and commits.loom/contexts/<name>.json
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:

  • state.jsonl and events.jsonl under .loom/.runtime/runs/<run_id>/

Next: Diagnostics ladder and Providers overview

loom runs​

Use loom runs to find a saved run by its recorded start, workflow and status. Add --json for one summary per line. Choose a returned ID explicitly for loom logs; recorded status does not establish process liveness.

loom logs​

Use loom logs <run_id> to read recorded event messages. Add --state for lifecycle transitions, --tail N for the last N records, or --json for complete record fields. See loom logs.

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​