> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambuild.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Environments

> Opt-in staged backfills, assessment, publishing, and lifecycle operations.

Virtual environments preserve StreamBuild's versioned deployment workflow. Enable them for the
whole invocation:

```toml theme={null}
[settings]
virtual_environments = true
```

The lifecycle is:

```text theme={null}
plan -> backfill -> audit backfill -> publish
```

## Backfill

```bash theme={null}
stb backfill --auto-approve
stb backfill --select orders --full-refresh --auto-approve
stb backfill --select orders --start-time 2026-07-01T00:00:00Z --auto-approve
```

Backfill creates deployment-specific model objects while the active stable views remain unchanged:

```text theme={null}
tbl__orders__20260729T120000Z_ab12cd
mv__orders__20260729T120000Z_ab12cd
```

The deployment ID is generated as `YYYYMMDDTHHMMSSZ_<six-hex>` unless supplied with
`--deployment-id`.

## Assess staged data

```bash theme={null}
stb audit backfill --deployment-id 20260729T120000Z_ab12cd
```

Assessment compares staged and active data, checks replay coverage, and runs applicable SQL audits.
Error-severity quality failures produce a `not_ready` assessment. Warning-severity failures appear
in the audit results but do not by themselves change the replay-readiness assessment.

<Warning>
  Assessment is an operator safety step, not an enforced publish lock. `stb publish` does not
  require a previously persisted ready result.
</Warning>

## Publish

```bash theme={null}
stb publish --deployment-id 20260729T120000Z_ab12cd
```

Publish creates or replaces stable views such as `tbl__orders` to read from the selected deployment
table. ClickHouse replaces each relation atomically, but the complete graph is **not graph-atomic**:
bindings are switched one relation at a time and StreamBuild reports that capability in output.

## Candidate selection

For `audit backfill` and `publish`, omitting `--deployment-id` works only when exactly one candidate
is available. Zero candidates is an error; multiple candidates produce explicit commands to choose
from.

## Operational commands

```bash theme={null}
stb doctor
DEPLOYMENT_ID="replace-with-deployment-id"
stb repair active-view --table tbl__orders --deployment-id "$DEPLOYMENT_ID"
stb reconcile
stb reconcile --apply
stb janitor
stb janitor --retention-days 30 --apply
```

* [`doctor`](/cli/doctor) diagnoses stable-view and deployment-reference problems.
* [`repair active-view`](/cli/repair) points one broken logical view at a known deployment.
* [`reconcile`](/cli/reconcile) previews or records a compatible live metadata baseline.
* [`janitor`](/cli/janitor) previews or removes stale deployment objects while protecting active and
  recent state.

These commands are virtual-environment-only. There is no automatic mode conversion or direct-mode
equivalent.