> ## 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.

# lua version

> Create, inspect, promote, and delete agent versions — atomic snapshots of everything pushed

`lua version` manages [agent versions](/concepts/releases-and-versions): numbered snapshots of the latest pushed version of every skill, webhook, job, processor, trigger, and workflow, plus the persona, the model, the default voice, and the MCP server configuration. `lua version promote` is the only action here that changes what end users get: it swaps every primitive version and the model to the chosen agent version at once. The persona is recorded in the version but not switched by it.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua version create [-m <message>] [--auto-push] [--commit-hash <hash>]
lua version list [--all] [--limit <n>] [--status <status>] [--json]
lua version show <version> [--json]
lua version diff <from> <to> [--json]
lua version promote <version>
lua version status
lua version delete <version> [--force]
```

## Description

[`lua push`](/reference/cli/push) pushes a version of a primitive; nothing changes for end users. `lua version create` snapshots the latest pushed version of every primitive into a new agent version with status `staged`. `lua version promote <n>` makes that agent version `active` for every end user, atomically, and promoting an earlier version is the rollback path for everything except the persona: a pushed persona is served from the agent's next message, agent versions record which persona version was current, and `lua version promote` does not change the served persona. To roll a persona back, deploy the earlier persona version with `lua deploy persona --set-version <n>`. [`lua deploy <type>`](/reference/cli/deploy) is the single-primitive shortcut: for a webhook, job, processor, or trigger it creates and promotes an agent version scoped to that primitive, and `lua workflows deploy` does the same for a workflow; for a skill it sets the active version the agent serves at once, which the next promote resets to the promoted agent version's pin. The release how-to is [Release an agent](/ship/releasing).

An agent version pins one version of each skill, webhook, trigger, job, preprocessor, postprocessor, and MCP server, plus the persona version, the model code, the bound voice, and any workflows. Devices and device triggers are not part of it. `create` needs a source backup, which every `lua push` except `lua push agent` records, and links the version to it so [`lua pull --version <n>`](/reference/cli/pull) can restore the matching files.

`create` exits 0 with `No changes since the latest version, so there is nothing to snapshot.` when nothing changed. An agent keeps at most 100 versions. `delete` is a soft delete: the version leaves listings but stays in history; the `active` version and the last remaining version cannot be deleted. With [`lua git connect`](/reference/cli/git) enabled, `create` commits and tags the project `lua/v<n>` and records the commit hash on the version; `promote` and `delete` add audit commits.

## Arguments

| Argument      | Values         | Description                                                                                |
| ------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `<version>`   | `3`, `v3`      | A positive integer, with or without a `v` prefix. `delete` rejects `current` and `active`. |
| `<from> <to>` | `2 3`, `v2 v3` | The two versions `diff` compares.                                                          |

## Options

| Option                 | Description                                                                                                                                | Default     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `-m, --message <text>` | `create`: description stored with the version. Prompted in a terminal when omitted; under `--ci` the version is created without a message. | none        |
| `--auto-push`          | `create`: run `lua push all --force` first, then create the version.                                                                       | off         |
| `--commit-hash <hash>` | `create`: git commit to record on the version. Set for you when git integration is on.                                                     | none        |
| `--all`                | `list`: return every version instead of the server's most recent 50.                                                                       | off         |
| `--limit <n>`          | `list`: cap the number of versions returned; must be 1 or more.                                                                            | 50 (server) |
| `--status <status>`    | `list`: `active`, `staged`, `superseded`, `deleted`, or `all`.                                                                             | `all`       |
| `--json`               | `list`, `show`, `diff`: print JSON instead of a table.                                                                                     | off         |
| `--force`              | `delete`: skip the confirmation prompt. The prompt is also skipped under `--ci` and when stdin is not a terminal.                          | off         |

## Statuses

| Status       | Meaning                                                                           |
| ------------ | --------------------------------------------------------------------------------- |
| `staged`     | Snapshotted, not live. Not the `staging` environment alias.                       |
| `active`     | Live for every end user. Exactly one version is active; `list` marks it with `*`. |
| `superseded` | Was active until a later promote. Promote it again to roll back.                  |
| `deleted`    | Soft-deleted with `lua version delete`. Cannot be promoted.                       |

## Output

`create` prints one line on stdout, ``✓ Created v<n> (staged). Run `lua version promote v<n>` to deploy.``, or `ℹ️  No changes since the latest version, so there is nothing to snapshot.` when nothing changed. `promote` prints `✓ Promoted v<n>. Previous active: v<m>.` (or `(No previous active version.)` on the first promote), or `v<n> is already active. No change.`; all on stdout, exit 0.

`list` returns versions newest first, highest number at the top, so a script reads the version `create` just made with `lua version list --limit 1 --json --ci | jq -r '.[0].version'`. It prints one row per version (`VERSION`, `STATUS`, `CREATED`, `BY`, `MESSAGE`); `--json` prints an array of `{ version, status, message, createdBy, createdByEmail, createdAt, commitHash, sourceManifestVersion }` without the `snapshot` field. `show` prints the creator, message, commit, model, persona version, and a count per primitive kind; `show --json` returns the full record with `snapshot`. `diff` prints `+` added, `-` removed, and `~` changed entries per kind, then persona, model, and voice changes; `diff --json` returns `{ fromVersion, toVersion, skills, webhooks, jobs, preprocessors, postprocessors, triggers, mcpServers, persona, model, voice }`, each kind as `{ added, removed, changed }`. `status` prints `TYPE`, `NAME`, `ACTIVE VERSION`, and `LOCAL` per local primitive, marks mismatches with `⚠`, and counts how many are ahead of the active version (push, then create and promote) or behind it (run `lua sync`).

## Examples

Create an agent version from what is pushed, with a message:

```bash theme={null}
lua version create -m "Add refund skill"
```

Push everything and create a version in one step, in CI:

```bash theme={null}
lua version create --auto-push -m "Release $GITHUB_SHA" --ci
```

Create a version in a script and promote the number it got:

```bash theme={null}
lua version create --ci -m "Release $GITHUB_SHA"
n=$(lua version list --limit 1 --json --ci | jq -r '.[0].version')
lua version promote "$n" --ci
```

Make version 4 live for every end user (promote 3 again to roll back):

```bash theme={null}
lua version promote 4
```

List the ten most recent versions as JSON:

```bash theme={null}
lua version list --limit 10 --json
```

Before the first `create`, `list` prints a hint instead of a table:

```text Output theme={null}
(no versions yet — run `lua version create` to make one)
```

Compare what changed between two versions:

```bash theme={null}
lua version diff 3 4 --json
```

Check which local primitives differ from the active version:

```bash theme={null}
lua version status
```

```text Output theme={null}
This agent has no versions. Per-primitive deploys (`lua deploy`) go live immediately for agents that are not under versioning.
```

Delete an old version without a prompt:

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

## Exit codes

| Code | Meaning                                                                                                                                                                                    |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | Success, including `nothing to snapshot` and `v<n> is already active. No change.`                                                                                                          |
| `1`  | The server refused: no backup yet, version not found, 100-version limit reached, deleting the active or last version, promoting a deleted version; or an invalid `<version>` or `--limit`. |
| `2`  | Not inside a project, or an unknown subcommand.                                                                                                                                            |
| `9`  | No credential, or the server rejected it.                                                                                                                                                  |
| `10` | The credential may not manage this agent.                                                                                                                                                  |
| `11` | The server or network is unavailable.                                                                                                                                                      |

## See also

* [Release an agent](/ship/releasing) — the push, create, promote flow
* [About releases and versions](/concepts/releases-and-versions)
* [`lua chat --agent-version`](/reference/cli/chat) — preview a staged version before promoting
* [`lua pull`](/reference/cli/pull) — restore the source files linked to a version
* [`lua deploy`](/reference/cli/deploy) — the single-primitive shortcut