Version Command

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.

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.

lua version promote is the recommended rollback path. It is instant, atomic, and requires no re-uploading of files. See lua version promote below and the deprecation notice on lua source rollback.

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

“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.”

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

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.

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.

lua version show 2
lua version show v2

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.

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

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.

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.

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

# 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

# 1. See what versions exist
lua version list

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

Audit

# 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 page for setup instructions, auto-push configuration, and troubleshooting.

Git Command — auto-commit and lua/v<N> tagging
Source Command — source-file history and workspace restore
Chat Command — lua chat --agent-version N to preview a version

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Version Command

Overview

Why versions?

The three version numbers

Statuses

Commands

`lua version create`

`lua version list`

`lua version show`

`lua version diff`

`lua version promote`

`lua version delete`

Typical workflows

Release

Rollback

Audit

Git integration

​Overview

​Why versions?

​The three version numbers

​Statuses

​Commands

​lua version create

​lua version list

​lua version show

​lua version diff

​lua version promote

​lua version delete

​Typical workflows

​Release

​Rollback

​Audit

​Git integration

​Related

Overview

Why versions?

The three version numbers

Statuses

Commands

`lua version create`

`lua version list`

`lua version show`

`lua version diff`

`lua version promote`

`lua version delete`

Typical workflows

Release

Rollback

Audit

Git integration

Related