Skip to main content

Loom CLI environment contract

This reference lists supported host inputs and their source locations. Update it when the CLI's environment behavior changes.

Supported host inputs​

  • LOOM_DOCKER_WORKSPACE_MOUNT — fixed; scope: loom run --local, layered config. Selects bind_mount or ephemeral_volume for the Docker workspace; the CLI flag has higher precedence. Sources: apps/loom-cli/cmd/runlocal/command.go, libs/loom-config/loom-config.go, libs/loom-config/effective.go, libs/loom-config/load.go, libs/loom-workflow/run.go, libs/loom-workflow/runtime_env.go.
  • LOOM_WORKFLOW — fixed; scope: layered config. Stands in for the --workflow flag of loom check, compile and run when the flag is omitted; the flag has higher precedence, then this variable, then defaults.workflow in .loom/config.yml and ~/.config/loom/config.yml. Sources: libs/loom-config/loom-config.go, libs/loom-config/defaults.go, libs/loom-config/effective.go, apps/loom-cli/cmd/workflowinput/defaults.go.
  • LOOM_FORMAT — fixed; scope: layered config. Stands in for the --format flag of loom check, compile and run when the flag is omitted; the flag has higher precedence, then this variable, then defaults.format in .loom/config.yml and ~/.config/loom/config.yml. Sources: libs/loom-config/loom-config.go, libs/loom-config/defaults.go, libs/loom-config/effective.go, apps/loom-cli/cmd/workflowinput/defaults.go.
  • LOOM_CONTEXT — fixed; scope: layered config. Stands in for the --context flag of loom check, compile and run when the flag is omitted; the flag has higher precedence, then this variable, then defaults.context in .loom/config.yml and ~/.config/loom/config.yml. Sources: libs/loom-config/loom-config.go, libs/loom-config/defaults.go, libs/loom-config/effective.go, apps/loom-cli/cmd/workflowinput/defaults.go.
  • LOOM_WEB_UPLOAD — fixed; scope: loom run. Explicit true opts in to post-run sanitized evidence delivery; every other explicitly supplied value disables credential lookup and network work. When absent, repository web.upload: true may opt in with exact local enrollment. Destination/enrollment/credential selection is captured before jobs; partial legacy selectors cannot borrow local configuration. Requires Web support for loom.ingestion.v2; older-server rejection warns without silent downgrade. Sources: apps/loom-cli/internal/webupload/config.go, apps/loom-cli/internal/webupload/repository.go. See the upload credential guide.
  • LOOM_WEB_UPLOAD_RETRY_INTERVAL — fixed; scope: loom run upload and saved-upload retry. Positive integer s/m/h duration, 1s through 1h; default 10s. Present values override web.uploadRetryInterval; an explicit --upload-retry-interval wins. Invalid/empty winning values fail without fallback. Timing alone does not opt in to normal upload. Source: apps/loom-cli/internal/webupload/timing.go.
  • LOOM_WEB_UPLOAD_TIMEOUT — fixed; scope: loom run upload and saved-upload retry. Positive integer s/m/h total budget, 1s through 1h; default 120s. Present values override web.uploadTimeout; an explicit --upload-timeout wins. The effective interval must not exceed this budget. Credential resolution and delivery share it. Source: apps/loom-cli/internal/webupload/timing.go.
  • LOOM_WEB_URL — fixed; scope: loom run upload and saved-upload retry. Validated HTTPS origin, optionally a root slash, with no userinfo, non-root path, query, or fragment; no redirects or TLS bypass. Source: apps/loom-cli/internal/webupload/config.go.
  • LOOM_WEB_PROJECT_ID — fixed; scope: loom run upload and saved-upload retry. Destination project UUID. Source: apps/loom-cli/internal/webupload/config.go.
  • LOOM_WEB_TOKEN_ENV — fixed; scope: loom run upload and saved-upload retry. Host environment-variable name holding an existing project-bound ingest:write bearer; token values are never accepted as command arguments or repository settings. Source: apps/loom-cli/internal/webupload/config.go.
  • LOOM_WEB_REDACT_ENV — fixed; scope: loom run upload and saved-upload retry. Optional comma-separated host environment-variable names whose nonempty values join the mapper known-value masking set; the ingestion token is always included. Actual output/diagnostic text is retained after literal and supported finite-variant masking, within the documented value and payload limits. Unknown/job-generated secrets and unsupported transformations are outside the guarantee. Source: apps/loom-cli/internal/webupload/config.go. See Optional Loom Web evidence upload for the trust boundary, transmitted data, local bundle, limits, and failure behavior.
  • OP_SERVICE_ACCOUNT_TOKEN — fixed; scope: 1Password management commands, op:// runtime resolution. Carries the 1Password service-account token; standalone management commands always require this fixed name. Sources: apps/loom-cli/cmd/secrets/op/command.go, libs/loom-config/loom-config.go, libs/loom-config/effective.go, libs/loom-workflow/run.go, libs/loom-secrets/op/manage/manage.go, libs/loom-secrets/op/manage/types.go, libs/loom-secrets/op/manage/validation.go, libs/loom-secrets/providers/op/adapter.go.
  • LOOM_KEEPASS_DB_<ALIAS>_PATH — dynamic; scope: layered config, KeePass management commands, keepass:// runtime resolution. Provides the database path. Alias keys are trimmed, uppercased, and map each non-ASCII-alphanumeric rune to an underscore. Sources: apps/loom-cli/cmd/secrets/keepass/vault_commands.go, libs/loom-config/loom-config.go, libs/loom-config/effective.go, libs/loom-secrets/keepass/manage/vaults.go, libs/loom-secrets/providers/keepass/adapter.go, libs/loom-secrets/internal/keepassdb/config.go.
  • LOOM_KEEPASS_DB_<ALIAS>_PASSWORD_ENV — dynamic; scope: layered config, KeePass management commands, keepass:// runtime resolution. Its value is the user-selected environment variable name that holds the vault password. Sources: libs/loom-config/loom-config.go, libs/loom-config/effective.go, libs/loom-secrets/keepass/manage/vaults.go, libs/loom-secrets/internal/keepassdb/config.go.
  • LOOM_KEEPASS_DB_<ALIAS>_KEYFILE_ENV — dynamic; scope: layered config, KeePass management commands, keepass:// runtime resolution. Its value is the user-selected environment variable name that holds the keyfile path. Sources: libs/loom-config/loom-config.go, libs/loom-config/effective.go, libs/loom-secrets/keepass/manage/vaults.go, libs/loom-secrets/internal/keepassdb/config.go.
  • Config environment-name pointers — user-selected; scope: loom run --local. KeePass passwordEnv/keyfileEnv and 1Password serviceAccountTokenEnv select names to dereference; they do not store secret values. Sources: libs/loom-config/loom-config.go, libs/loom-config/effective.go, libs/loom-config/init.go, libs/loom-workflow/run.go.
  • env://<VAR_NAME> — user-selected; scope: workflow secret resolution through the env provider. Reads the caller-selected host variable named by the URI; the workflow secret target name remains a runtime output. Sources: libs/loom-secrets/providers/env/adapter.go.
  • --value-from-env <NAME> — user-selected; scope: KeePass and 1Password item create/update commands. Reads a required non-empty field value from the caller-selected variable without placing it on the command line. Sources: apps/loom-cli/cmd/secrets/keepass/item_commands.go, apps/loom-cli/cmd/secrets/keepass/options.go, apps/loom-cli/cmd/secrets/op/item_commands.go, apps/loom-cli/cmd/secrets/op/options.go.
  • --password-from-env <NAME> / --keyfile-from-env <NAME> — user-selected; scope: KeePass vault create/update commands. Reads new vault credentials from one or both caller-selected variables; at least one is required. Sources: apps/loom-cli/cmd/secrets/keepass/vault_commands.go, libs/loom-secrets/keepass/manage/types.go.

Explicit exclusions​

These surfaces are intentionally outside the host-facing CLI contract.

  • Installer-only variables — scope: install-loom.sh bootstrap process; examples: LOOM_INSTALL_DIR, LOOM_BASE_URL. Installer inputs configure download and placement before the Loom CLI runs. Sources: install-loom.sh.
  • Predefined and runtime-injected job variables — scope: compiled job execution; examples: CI_DEBUG_TRACE, LOOM_RUN_ID, LOOM_PROVIDER, LOOM_PROJECT_DIR. CI_* and LOOM_* registry values are produced for jobs rather than read as supported host CLI settings. Sources: libs/loom-variables/internal/resolvers/ci/job.go, libs/loom-variables/internal/resolvers/loom/loom.go, libs/loom-runlocal/workspace.go.
  • Workflow variable and secret output names — scope: job environment assembly; examples: variables.<NAME>, secrets.<NAME>. Workflow keys and secret target names are outputs injected into a job, not a finite set of host inputs. Sources: libs/loom-runlocal/provider.go, libs/loom-secrets/runtime/runtime.go.
  • Ambient process and platform environment — scope: host provider inheritance and process execution; examples: HOME, PATH. Inherited HOME, PATH, and other ambient values are not Loom-owned CLI settings. Sources: libs/loom-runlocal/provider.go, libs/loom-workflow/runtime_config.go.