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 |
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"
No staged changes since the previous version.
✓ 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. |
2 or v2 for both arguments.
lua version diff 1 2
lua version diff v1 v2 --json | jq '.changed'
superseded. Promoting the already-active version is a graceful no-op.
lua version promote 2
# ✓ Promoted v2. Previous active: v1.
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
- 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.
