lua version

lua version manages agent 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

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

lua version create -m "Add refund skill"

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

lua version create --auto-push -m "Release $GITHUB_SHA" --ci

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

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

lua version promote 4

List the ten most recent versions as JSON:

lua version list --limit 10 --json

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

Output

(no versions yet — run `lua version create` to make one)

Compare what changed between two versions:

lua version diff 3 4 --json

Check which local primitives differ from the active version:

lua version status

Output

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:

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.

SDK

CLI

REST API

Synopsis

Description

Arguments

Options

Statuses

Output

Examples

Exit codes

See also

​Synopsis

​Description

​Arguments

​Options

​Statuses

​Output

​Examples

​Exit codes

​See also

Synopsis

Description

Arguments

Options

Statuses

Output

Examples

Exit codes

See also