Installing & managing workspaces

A workspace is a core.workspace.v1 record. Managing workspaces means emitting and reading those records on your instance's workspace catalog — nothing is compiled in, and nothing needs a restart. The spl workspace commands below are the runtime surface for that.

Install a workspace

spl workspace install ./my-workspace.json

install reads a core.workspace.v1 document file, checks it against the workspace body shape, and emits it as a record onto your instance's workspace catalog. The moment the record lands, the workspace is live — open it at its slug route.

If the file is not a well-formed workspace document — for example, it is missing meta.slug, or a region is not a valid projection document — the install is refused and nothing is emitted. See Authoring a workspace for the document format.

List installed workspaces

spl workspace list

This folds the workspace catalog and shows the latest record for each slug — title, lifecycle, and content hash. Because every install is a new immutable record, list always reflects the most recent version of each workspace.

Add -o json for a machine-readable list.

Inspect a workspace

spl workspace show tasks

show <slug> prints the full core.workspace.v1 body of the named workspace — meta, capabilities, regions, and lifecycle. Read the capabilities block before you trust a workspace someone else wrote: it is the complete list of what the surface may emit and where it may navigate.

Update a workspace

spl workspace update tasks ./my-workspace.json

update <slug> <file> re-emits a workspace under an existing slug. The file's meta.slug must match the slug you name. Records are immutable, so this appends a new record rather than mutating the old one — the previous version stays addressable forever, and list resolves the latest by clock.

Updating an unchanged document is a no-op: identical content produces an identical hash, and the catalog already holds that record.

The lifecycle field

Every workspace body carries a lifecycle field with one of three values:

Lifecycle is not separate engine state — it is just a field on the record. Moving a workspace between states means emitting a new record with a different lifecycle value. The latest record by clock for a given slug is the authoritative state.

Archive a workspace

spl workspace archive tasks

archive <slug> re-emits the workspace's latest body with lifecycle: "archived". This is a soft delete:

• The workspace stops appearing in spl workspace list.
• It can no longer be newly subscribed to.
• Existing subscriptions are grandfathered — subscribers keep resolving it.
• Every historical record stays addressable forever; records are immutable.

To bring an archived workspace back, update it with a body whose lifecycle is published again.

Subscribe to a workspace

spl workspace subscribe <workspace-hash>

subscribe records your relationship to a workspace — it emits a core.subscription.v1 record naming the workspace by its content hash. Subscriptions carry your pin (which version you track), any permission grants you have accepted, and your pinned-publisher choice. unsubscribe <workspace-hash> re-asserts the relationship as inactive; it never deletes, because records are immutable.

Subscriptions are namespace-local by default. Pass --federated on subscribe to make a subscription visible to your peers.

Discovering workspaces

The workspace catalog is just records. You can query it directly without the spl workspace commands:

spl query --kind core.workspace.v1

This is the same fold spl workspace list performs. Filtering on body.kind is how any tool — a browser, a script, another instance — finds the workspaces an instance serves.

See also

• Workspaces — what a workspace is.
• Authoring a workspace — write the document you install.
• Tutorial: Build your first workspace — the happy path, end to end.
• core.workspace.v1 schema