Skip to main content

loom config

Inspect Loom's layered runtime config.

Use loom config when you want to see the runtime-only defaults that Loom resolves before local execution. It is the fastest way to answer:

  • Which config files did Loom discover here?
  • Which runtime value won after layering?
  • What will loom run --local start from before any one-off flags are applied?

loom config does not define workflows. .loom/workflow.yml remains the executable workflow source of truth.

Canonical command usage​

Use the generated core CLI command reference for exact loom config, loom config init, and loom config show synopsis, flags, and displayed defaults.

loom config​

Behavior​

loom config is a command group. Invoking it without a subcommand:

  • prints help for the group
  • lists the available config subcommands
  • exits successfully

Today the group contains two subcommands: init and show.

Example output​

Inspect layered runtime config

Usage:
  loom config [command]

Available Commands:
  init        Create a starter runtime config file
  show        Print the effective layered runtime config

Flags:
  -h, --help   help for config

Use loom config init to create a starter file or loom config show to inspect the merged defaults.

loom config init​

Create a starter runtime config file at the standard Loom location for either the current repo or the current user.

What it is for​

Use loom config init when you want to:

  • bootstrap .loom/config.yml in the current repo
  • bootstrap ~/.config/loom/config.yml for machine-local defaults
  • start from a commented template that shows the supported runtime-config keys

Behavior​

loom config init:

  • creates parent directories when needed
  • writes a comment-heavy starter file with examples for the supported keys
  • fails if the target config file already exists

For the default repo-scoped target, Loom walks upward from the current directory until it finds one of these repo markers:

  • .loom/config.yml
  • .loom/workflow.yml
  • .git

If no repo root is discovered, loom config init fails instead of creating a stray .loom/config.yml outside a Loom repo.

Examples​

Create a repo-scoped starter config in the current repo:

loom config init

Create a user-scoped starter config:

loom config init --user

What it writes​

The starter file is valid YAML and includes commented examples for:

  • runtime.docker.workspaceMount
  • providers.keepass.aliases.<name>.path
  • providers.keepass.aliases.<name>.passwordEnv
  • providers.keepass.aliases.<name>.keyfileEnv
  • providers.op.serviceAccountTokenEnv

The generated file does not write secret values. It shows env var names only.

loom config show​

Print the effective runtime config after Loom applies built-in defaults, config files, and supported environment overlays.

What it is for​

Use loom config show when you want to:

  • inspect the merged runtime config from your current directory context
  • confirm which config files Loom discovered
  • test a one-off env overlay before running locally

What it reads​

loom config show resolves config in this order:

Priority (lowest to highest)Source
1Built-in defaults
2~/.config/loom/config.yml if it exists
3<repo-root>/.loom/config.yml if it exists
4Supported environment overlays from the current process environment

The built-in default and supported environment overlays are:

  • Built-in default: runtime.docker.workspaceMount: ephemeral_volume
  • Environment overlay: LOOM_DOCKER_WORKSPACE_MOUNT
  • Environment overlays: LOOM_KEEPASS_DB_*

Repo config is discovered from the current working directory. Loom walks upward until it finds one of these repo markers:

  • .loom/config.yml
  • .loom/workflow.yml
  • .git

If no repo root is discovered, the repo config layer is skipped.

Merge behavior​

  • Later layers override earlier layers only for fields they set.
  • KeePass aliases merge by alias name, so one layer can set path and a later layer can add passwordEnv or keyfileEnv.
  • Relative KeePass path values from config files are resolved relative to the directory that defined them.
  • Empty env values are ignored instead of treated as overrides.

What it prints​

On success, loom config show writes YAML to stdout.

The rendered YAML can include:

  • sources.userConfigPath when ~/.config/loom/config.yml existed
  • sources.repoConfigPath when <repo-root>/.loom/config.yml existed
  • runtime.docker.workspaceMount
  • providers.keepass.aliases
  • providers.op.serviceAccountTokenEnv

If neither config file exists, the sources block is omitted. The command still prints the effective config, including built-in defaults and any supported environment overlays that are present.

providers.op.serviceAccountTokenEnv is the env var name reference, not the token value itself.

Example output​

sources:
  userConfigPath: /home/alex/.config/loom/config.yml
  repoConfigPath: /work/repo/.loom/config.yml
runtime:
  docker:
    workspaceMount: ephemeral_volume
providers:
  keepass:
    aliases:
      team/app:
        path: /home/alex/.config/loom/vaults/team-app.kdbx
        passwordEnv: ENV_PASSWORD
        keyfileEnv: TEAM_KEYFILE
      prod:
        path: /work/repo/.loom/vaults/prod.kdbx
  op:
    serviceAccountTokenEnv: USER_OP_TOKEN

Examples​

Inspect the effective config from your current directory:

loom config show

Inspect the effective config while testing a one-off Docker mount override:

LOOM_DOCKER_WORKSPACE_MOUNT=bind_mount loom config show

Check whether Loom discovered user and repo config files:

loom config show | sed -n '1,12p'

Confirm that you are using runtime config, not workflow YAML:

loom config show
loom check

loom config show inspects layered runtime config. loom check validates .loom/workflow.yml. They read different surfaces on purpose.

What it does not do​

loom config show does not:

  • write or modify config files
  • print per-field provenance for each merged value
  • print resolved secret values such as a 1Password service account token
  • show loom run --local --docker-workspace-mount ..., because that flag applies at run time rather than config-inspection time
  • change what loom check or loom compile read; those commands still operate on workflow inputs rather than layered runtime config

Relationship to loom run --local​

loom run --local consumes the same layered runtime config, but it has one extra Docker mount override above what loom config show prints:

  1. Built-in defaults
  2. ~/.config/loom/config.yml
  3. .loom/config.yml
  4. LOOM_DOCKER_WORKSPACE_MOUNT
  5. loom run --local --docker-workspace-mount ...

That final CLI flag affects only the current run.

  • loom run reads the layered runtime config during local execution
  • loom check validates workflow structure only
  • loom compile compiles workflow input to Graph IR JSON