Skip to main content
lua push compiles the project and pushes versions to the platform. A push by itself changes nothing for end users except the agent configuration: a pushed persona and model are served from the agent’s next message, while a pushed skill, webhook, job, processor, trigger, or workflow version exists on the server and goes live only through lua version promote, lua deploy, or lua workflows deploy. Verified against lua-cli 3.33.0.

​
Synopsis

​
Description

Every form except backup starts with a compile that also reconciles lua.skill.yaml with the server: primitives the agent does not have yet are registered and their ids written to the file, and each row’s version is reset to the server’s active version. A version edited by hand therefore does not survive; use --set-version or --force.

​
Stage-all push

Bare lua push bumps each primitive’s patch version above both the file’s version and the server’s highest, pushes skills, webhooks, triggers, jobs, preprocessors, postprocessors, devices, device triggers, and voices, upserts MCP servers, pushes the agent configuration, and ends with a source backup. It never prompts. Workflows are not included; push them with lua push workflow. Per-item failures are listed under ⚠️ <n> component(s) failed to push: and the command still exits 0, so a script must grep the output for component(s) failed to push. On success it prints the next step: lua version create, then lua version promote <n>. lua push all --force runs exactly the same path as bare lua push; the only difference is that all refuses without --force (The "all" type requires the --force flag, exit 1). --auto-deploy is ignored on both with the warning --auto-deploy is ignored when agent versioning is on., because a change to the whole agent goes live through agent versions.

​
Single-primitive push

lua push <type> selects the entity by --name, automatically when there is one, or by prompt; --name without a type exits 1 with Type must be specified when using the --name option. The version is --set-version when given; otherwise the next patch above the file and server versions with --force; otherwise a prompt that defaults to the next patch. After the push the command asks whether to deploy to production: --auto-deploy deploys without asking, waiting 3 seconds and retrying up to three times, while --force alone skips the question and deploys nothing. On a versioned agent, --auto-deploy on a skill is reset by the next lua version promote; on a webhook, job, processor, or trigger it creates and promotes a scoped agent version (see lua deploy). A fresh-from-disk source backup then runs; if it fails, the command exits non-zero even though the primitive is already pushed, and the message says so. Finally the project source is attached to each skill version so the admin dashboard’s Builder shows CLI edits; --no-include-source skips this non-fatal step. Once the agent has an agent version, a single-primitive push prints a deprecation notice pointing at bare lua push.

​
Agent configuration push

lua push agent, alias persona, replaces the agent-level configuration with what src/index.ts declares, after a confirmation unless --force is passed. It creates a new persona version when the code has persona text, pushes the model or model resolver, modelSettings, batching, the browser switch, and the linked voices, and pushes the routing description and governance only when the code sets them. Fields absent from the code are cleared on the server: no model means the platform default, no modelSettings means provider defaults, no voices means no links. With neither persona nor model it exits 1 with No agent configuration to push. A pushed persona is served from the agent’s next message, on a versioned agent as well as an unversioned one. lua deploy persona --set-version <n> switches the served persona to an earlier version at once. Agent versions record which persona version was current, but lua version promote does not change the served persona: to roll a persona back, deploy the earlier persona version. --auto-deploy runs that deploy on the version just pushed, which changes nothing further, and the command’s hint You can deploy the persona version later using: lua deploy refers to the same no-op.

​
MCP servers, backups, and workflows

lua push mcp upserts the MCP server by name; --auto-deploy activates it. lua push backup pushes a content-addressed backup of the project files, skipped when nothing changed unless --force; it compiles first only when dist-v2/ is missing and --fresh is not set, and it refuses to overwrite a backup that another machine pushed since your last push unless --force. Each backup is a source version that lua source lists and lua init or lua pull restores. lua push workflow warns with env-key-missing when the workflow reads env() keys that have no value in the target environment. A pushed workflow goes live with lua workflows deploy <name> -v latest; lua deploy has no workflow type. A version that already exists is refused with is not pushed: … already exists and a hint to use --force; bare lua push retries once after re-reading the server’s highest version.

​
Arguments

​
Options

​
Examples

Stage everything, then create and promote an agent version:
Stage everything from a script; progress goes to stderr and the result to stdout:
Output
No component failed in this run. When one does, the block ⚠️ <n> component(s) failed to push: follows the per-item lines, with one <kind> "<name>": <error> line and a 💡 Diagnose: lua logs … line per failure, and the exit code stays 0. Fail a CI job on it:
Push one skill at an explicit version without prompts and make it live (on a versioned agent the next lua version promote resets it):
Push the persona and model from src/index.ts:
Push a workflow and fail if any env() key is unset in production:
Recover the source backup after a push reported Source backup failed:

​
Exit codes

​
See also