CLI Reference
The wl CLI is your daily interface to Workloom. Every command is designed around the principle of explicit, predictable behavior — no silent writes, no hidden state changes.
Installation
npm install -g @workloom/cli
Commands
wl init
Initialize a Workloom binding in the current directory.
wl init
Creates .loom/binding.toml with workspace configuration. This file should be committed to your repository.
wl auth
Authenticate with the Workloom registry.
wl auth
Uses OAuth 2.0 Device Authorization Grant (RFC 8628). Opens a browser for interactive login. Tokens are stored in the OS keychain (with file fallback at ~/.config/loom/).
wl bind
Bind the current project to a workspace.
wl bind <org>/<workspace>
Example:
wl bind acme/frontend-team
wl validate
Validate workspace and package manifests against Zod schemas.
wl validate [path]
Validates trust classification, projection policy, provider capabilities, and telemetry redaction rules. Exits non-zero with diagnostics on failure.
wl pull
Fetch workspace desired state and render provider-specific files.
wl pull [options]
| Flag | Description |
|---|---|
--dry-run | Show render plan without writing files |
--locked | Use locked versions only (deterministic installs) |
--on-conflict <policy> | Override conflict policy: fail, keep-local, restore, promote-to-override |
Default behavior: If a locally-modified file conflicts with the new desired state, wl pull exits with code 4 (conflict) and does NOT overwrite.
wl push
Create a draft package version.
wl push --draft
Uploads package assets to the registry as a draft. Never silently publishes — always requires explicit wl publish.
wl publish
Promote a draft version to pending review.
wl publish <scope>/<name>@<version>
Example:
wl publish @acme/frontend-baseline@1.2.0
wl sync
Apply desired state to local files.
wl sync [options]
| Flag | Description |
|---|---|
--check | Verify without writing — for CI. Exit 0 = clean, non-zero = drift |
--locked | Apply only locked desired state |
CI usage:
wl sync --check
# Exit 0 = all files match desired state
# Exit 1 = drift detected
wl status
Show workspace info, current revision, and drift state.
wl status
Output includes:
- Workspace name and revision
- Package versions installed
- File ownership states
- Drift summary
wl diff
Show file-level diffs against the installed package version.
wl diff [file...]
wl restore
Restore Workloom-owned files to their desired state.
wl restore [file...]
Only restores files that Workloom owns (state = managed or locally_modified). Never deletes unknown files.
wl rollback
Roll back to a previous workspace revision.
wl rollback --workspace-revision <n>
Example:
wl rollback --workspace-revision 11
Exit Codes
| Code | Meaning |
|---|---|
0 | Success / clean |
1 | Drift detected / validation failed |
2 | Auth error |
3 | Network error |
4 | Conflict (local modification vs remote update) |
5 | Policy violation (trust gate blocked write) |
Configuration
.loom/binding.toml
Your project's workspace binding. Committed to git.
[workspace]
org = "acme"
name = "frontend-team"
[targets.root]
path = "."
providers = ["claude", "codex"]
[targets.web]
path = "apps/web"
providers = ["claude"]
[conflict]
policy = "fail" # fail | keep-local | restore | promote-to-override
.loom/lock.json
Resolved versions and content hashes. Optionally committed for deterministic installs.
.loom/state.json
Local ownership state. Gitignored — tracks which files Workloom manages and their current state.
Environment Variables
| Variable | Description |
|---|---|
WL_TOKEN | API token (CI/service accounts) |
WL_REGISTRY | Registry URL override |
WL_CONFIG_DIR | Override config directory (default: ~/.config/loom/) |
WL_NO_COLOR | Disable colored output |