Skip to main content

loom web setup project

Connect the current repository to an owned Loom Web project. Run the command from the repository, or a directory beneath it. It writes only the destination and upload choice to .loom/config.yml:

web:
  version: 1
  url: https://loom.example
  projectId: 11111111-1111-4111-8111-111111111111
  upload: false

The URL is a canonical HTTPS origin and the project ID is an immutable UUID. Setup saves UUIDs in lowercase canonical form. The complete web tuple comes from this repository file; user config and environment values cannot replace one field of it. With no web block, runs remain local. Unknown fields and unsupported versions fail explicitly. The editor preserves unrelated config and comments and rejects unsafe YAML shapes or a file changed during setup.

First authorize an account with the capabilities you need, then select an existing owned project or create one:

loom auth account --url https://loom.example --flow browser
loom web setup project --url https://loom.example --account ACCOUNT_ID

Interactive setup lists every page of active projects owned by that account and shows each name, slug and UUID. You may select one or enter create and supply a project name and owner-unique slug. The command then shows the destination and asks whether future finalized evidence may be uploaded. Press Enter for no. Authentication alone does not enable uploads.

For scripts, supply every choice, including an explicit upload value:

loom web setup project --url https://loom.example --account ACCOUNT_ID \
  --project-id 11111111-1111-4111-8111-111111111111 --upload=false

loom web setup project --url https://loom.example --account ACCOUNT_ID \
  --create-name 'My project' --create-slug my-project --upload=true

Selecting an existing project requires projects:read. Creating one requires projects:create; a create-only grant cannot list projects. A missing capability requires a separate loom auth account authorization with that capability. A slug conflict or uncertain create response is reconciled against owned projects when read access exists. The command reports a matching project's safe UUID and requires explicit selection; it does not silently create under another slug. If the Web project exists but saving local config fails, rerun with its reported --project-id.

If you already have a stored project credential for an exact existing project, connect locally without account management access:

loom web setup project --url https://loom.example --account ACCOUNT_ID \
  --project-id 11111111-1111-4111-8111-111111111111 \
  --local-connect --upload=false

When both a project-only and an account-derived credential are stored for that destination, add --credential-kind project-only or --credential-kind account-derived. This path makes no project-management request and reports “server authorization not checked.” It cannot prove the project exists or is still active. It never uploads test evidence to probe access.

Local enrollment binds the canonical repository root, Web origin, account, project and chosen credential identity in ~/.config/loom/auth.json. A cloned repository or changed destination requires setup again. Tokens, account grants and store references never enter .loom/config.yml. Host jobs running as the same OS user can read that user's home; use trusted host workflows while credentials are stored.

Optional web.uploadRetryInterval and web.uploadTimeout values configure the delivery interval and total budget; setup preserves existing values. See delivery timing and saved-run retry for exact precedence, duration bounds and explicit recovery.