# Deployments

| Command | Purpose |
|---|---|
| `vatio push [--force]` | Update `preview`; it runs no tests. The first push signs in like `login` |
| `vatio publish [--force]` | Take `preview` live with its knowledge changes |
| `vatio rollback` | Put live back to the previous snapshot: configuration and knowledge together |
| `vatio status` | Show deployment state |
| `vatio env [preview\|live]` | One environment: its token, widget snippet, test link, knowledge changes and conflicts; default `preview` |
| `vatio env list` | Both environments and what each runs |
| `vatio diff [--env NAME]` | Compare local files with a deployment; default `preview` |
| `vatio diff --stat` / `--name-only` / `--format json` / `--full` | Select diff detail or output format |

There are two environments: `preview`, the next version, which `push`
updates, and `live`, what visitors talk to. `--env` takes one of the two
(`staging` and `sandbox` still mean `preview`); any other name is an error.
`push` cannot target `live`: publishing is a separate, deliberate step. `diff`
compares your **local directory** with a deployment, so push local edits before
publishing them.

## The publish gate

Before the first publish there is nothing live to protect, so `publish` always
goes through. When preview is already live's version there is nothing to take
live either: `publish` moves only preview's knowledge changes and prints a
notice saying so. Otherwise, `publish` takes preview live only once
[`vatio eval`](https://vatio.ai/docs/cli/improve) has tested preview's current version, and refuses
with one of these `error_key`s otherwise:

| `error_key` | What it means | Next |
|---|---|---|
| `evals_missing` | Preview's version has not been tested | `vatio eval`, then publish |
| `evals_running` | Its tests are still running | `vatio eval` waits for them, then publish |
| `evals_regressed` | A report that passes on live fails on preview; the CLI lists each one by id and title | Fix it, `push` and `eval` again |

Reports that still fail on both do not block: a partial fix can ship. When
`publish` goes through, the reports preview passed are resolved, with the
version that fixed them. `publish --force` publishes over a regression anyway,
and its failing results go live with it; use it only when you know why the
report fails.

## Pushing over someone else's push

Once the workspace is published, `push` refuses to replace a preview that holds
an unpublished push from another git branch (`preview_has_unpublished_push`):
whoever pushed it has not published it yet. Publish it first, or
`push --force` to replace it. The CLI sends the current git branch with each
push for this.

`publish` is refused when live changed a knowledge entry preview also changed;
see [Conflicts](https://vatio.ai/docs/knowledge#conflicts).

See [Deployments](https://vatio.ai/docs/deployments) for what an environment actually holds, and
what a rollback does and does not restore.