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

# Version Command

> Create, inspect, promote, and roll back atomic versions of your agent

## Overview

`lua version` manages **agent versions** — atomic snapshots of your agent's complete deployed state (skills, webhooks, jobs, processors, MCP servers, persona, and model) that you can inspect, diff, and switch between instantly.

```bash theme={null}
lua version create --auto-push -m "checkout flow v2"   # Push + snapshot in one step
lua version list                                        # See all versions
lua version diff 1 2                                    # What changed between v1 and v2?
lua version promote 2                                   # Make v2 live — instant, no re-upload
```

## Why versions?

A `lua push` updates individual primitives (a skill, a webhook, a persona) one by one. An agent version **pins the exact combination of everything** at a moment in time: which version of every skill, what model, which persona text, which MCP servers and how they were configured.

Promoting a version swaps the whole agent state **atomically** — all of it changes at once, with no in-between state where some primitives are old and some are new. Rolling back is just promoting an older version.

<Note>
  `lua version promote` is the recommended rollback path. It is instant, atomic, and requires no re-uploading of files. See [`lua version promote`](#lua-version-promote) below and the deprecation notice on [`lua source rollback`](/cli/source-command).
</Note>

## The three version numbers

When you run `lua version create --auto-push`, the output shows three different counters. They track separate things:

| Counter           | Example output       | What it tracks                                                          |
| ----------------- | -------------------- | ----------------------------------------------------------------------- |
| Primitive version | `user-skill v1.0.15` | Semver of one skill/webhook/job — bumped on each push of that primitive |
| Source backup     | `Backup at v3`       | Your project's source-file history (`lua source list`)                  |
| **Agent version** | `Created v2`         | **The atomic agent snapshot — what `lua version` manages**              |

These counters are independent. Pushing a single skill increments that skill's primitive version and creates a new source backup, but does **not** create a new agent version. Only `lua version create` creates a new agent version.

## Statuses

Every agent version has one of four statuses:

| Status       | Meaning                                                            |
| ------------ | ------------------------------------------------------------------ |
| `active`     | Currently serving — starred (`*`) in `lua version list`            |
| `staged`     | Snapshotted and awaiting promotion — not yet live                  |
| `superseded` | Was previously active; replaced when another version was promoted  |
| `deleted`    | Soft-deleted; still listed and inspectable, but cannot be promoted |

<Warning>
  **"staged" does not mean "staging environment."** A staged agent version is unrelated to your push deploy target (staging vs production) and unrelated to git's staging area. Here, "staged" simply means "snapshotted, awaiting promote."
</Warning>

## Commands

### `lua version create`

Snapshots the agent's current pushed state as a new `staged` version.

| Option                 | Description                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `-m <message>`         | A short description stored with the version (e.g. `"checkout flow v2"`).                                    |
| `--auto-push`          | Push all local changes first, then snapshot. Equivalent to `lua push all` followed by `lua version create`. |
| `--commit-hash <hash>` | Associate a specific git commit hash with this version (recorded in the snapshot metadata).                 |

```bash theme={null}
lua version create -m "stable before A/B test"
lua version create --auto-push -m "checkout flow v2"
```

If nothing has changed since the last snapshot, the command exits with:

```
No staged changes since the previous version.
```

On success:

```
✓ Created v2 (staged). Run 'lua version promote v2' to deploy.
```

### `lua version list`

Prints a table of agent versions with columns VERSION, STATUS, CREATED, BY, and MESSAGE. The active version is starred.

| Option         | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `--all`        | Show all versions (overrides `--limit`).                                 |
| `--limit <n>`  | Cap output at `n` versions. Must be ≥ 1. Default: 20.                    |
| `--status <s>` | Filter by status: `active`, `staged`, `superseded`, `deleted`, or `all`. |
| `--json`       | Output clean JSON — pipeable to `jq` and other tools.                    |

```bash theme={null}
lua version list                           # recent versions, active starred
lua version list --all                     # full history
lua version list --status staged           # only staged versions
lua version list --json | jq '.[0]'        # first entry as JSON
```

### `lua version show`

Shows the full snapshot for a version: per-type primitive counts, model, persona version, creator email, message, and recorded commit hash (if any).

Accepts either `2` or `v2` as the version argument.

```bash theme={null}
lua version show 2
lua version show v2
```

<Note>
  `lua version show` reports what is on the **server** for the agent at the time of the snapshot — not what is in your local project directory. A skill that exists server-side but has been removed from your local workspace is still part of the agent and will appear in the snapshot.
</Note>

### `lua version diff`

Shows what changed between two versions: added, removed, and changed primitives by name and version. Persona is compared by **content**, so re-pushing identical persona text shows `(unchanged)`. MCP configuration changes name the specific fields that changed. Model changes are included.

| Option   | Description                |
| -------- | -------------------------- |
| `--json` | Output diff as clean JSON. |

Accepts `2` or `v2` for both arguments.

```bash theme={null}
lua version diff 1 2
lua version diff v1 v2 --json | jq '.changed'
```

### `lua version promote`

Instantly activates a version. The previously active version becomes `superseded`. Promoting the already-active version is a graceful no-op.

```bash theme={null}
lua version promote 2
# ✓ Promoted v2. Previous active: v1.
```

There is no confirmation prompt — promotion is instant and the previous state is preserved as `superseded`, so you can always promote back.

### `lua version delete`

Soft-deletes a version. Deleted versions remain listed and inspectable with `lua version show`, but can no longer be promoted.

| Option    | Description                   |
| --------- | ----------------------------- |
| `--force` | Skip the confirmation prompt. |

```bash theme={null}
lua version delete 3
lua version delete 3 --force
```

Guard-rails:

* You cannot delete the **active** version. Promote a different version first.
* You cannot delete the **only remaining** version.

## Typical workflows

### Release

```bash theme={null}
# 1. Push everything and snapshot in one step
lua version create --auto-push -m "checkout flow v2"

# 2. Preview the new version in chat before promoting
lua chat --agent-version 2

# 3. Promote when satisfied
lua version promote 2
```

### Rollback

```bash theme={null}
# 1. See what versions exist
lua version list

# 2. Promote the last-known-good version — instant, no re-upload
lua version promote 1
```

### Audit

```bash theme={null}
# Diff two versions to understand what changed
lua version diff 1 2

# Inspect the full snapshot of a specific version
lua version show 2

# Or pipe to jq for scripting
lua version show 2 --json | jq '.snapshot'
```

## Git integration

When you have run `lua git connect`, every `lua version create` automatically commits your project and tags the commit `lua/v<N>`, where `N` is the new version number. The commit hash is recorded in the version snapshot and visible in `lua version show`.

See the [Git Command](/cli/git-command) page for setup instructions, auto-push configuration, and troubleshooting.

## Related

* [Git Command](/cli/git-command) — auto-commit and `lua/v<N>` tagging
* [Source Command](/cli/source-command) — source-file history and workspace restore
* [Chat Command](/cli/chat-command) — `lua chat --agent-version N` to preview a version