lua push compiles the project and pushes versions to the platform. A push by itself changes nothing for end users except the model and model settings in the agent configuration, which are served from the agent’s next message. A pushed persona is staged (the hint says staged — NOT activated) and goes live only through lua deploy persona --set-version <n>; 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.
Requires lua-cli 3.36.0 or later.
Synopsis
Description
Every form exceptbackup 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
Barelua 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. From lua-cli 3.36.0, workflows are included and each pushed workflow version is made live at once — a workflow is versioned on its own, not through an agent version, so this is the one part of a bare push that goes live immediately, printed under 🚀 Activating workflow version(s); on earlier releases workflows are not included and are pushed 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. From lua-cli 3.42.0, web apps are included and staged like the other primitives. 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 staged, not served: the command prints 💡 Persona v<n> staged — NOT activated. What the agent serves is unchanged. and names the activation command, on a versioned agent as well as an unversioned one. lua deploy persona --set-version <n|latest> --force activates it (or switches back 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 activate or roll a persona back, deploy that persona version. --auto-deploy activates the version just pushed without asking; without it the command offers the deploy (default No), and --force alone skips the question and leaves the version staged. Until the version is activated lua sync --check reports persona drift, because drift is measured against the version the agent serves. Requires lua-cli 3.39.4 and later; on earlier CLIs the push served the persona at once.
Web apps
lua push webapp builds the app’s pages with the Vite installed in its web/ folder, uploads them with the route bundle, and creates a web-app version. Run npm install in web/ first. It never asks to deploy and --auto-deploy does nothing for it: a web-app version goes live with the agent version that pins it, so the command ends with Staged but NOT live yet and the lua version create and lua version promote <version> steps. A build that breaks a limit is refused before anything is uploaded: an entry HTML over 256 Ki characters, more than 1000 assets, an asset over 8 MiB or with a file name outside letters, digits, ., _, -, and /, or more than 200 routes. Requires lua-cli 3.42.0 or later; see Write routes and pages.
MCP servers, backups, and workflows
lua push mcp upserts the MCP server by name; --auto-deploy activates it. A push only creates or updates servers from your project: a custom MCP server added from the Tools page or the admin dashboard is never overwritten or taken over, and a project server can’t take the name Lua gives a custom server’s tools on that agent (for Acme CRM, mcp_acme_crm); that push fails. 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. lua push browser --name <name> creates or updates one named browser by name; run lua push agent afterwards so the agent picks up its browsers list. Bare lua push and lua push all push every named browser too.
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:Output
⚠️ <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:
lua version promote resets it):
src/index.ts:
env() key is unset in production:
Source backup failed:
Exit codes
See also
- Release an agent — push, version create, promote
lua versionandlua deploy- lua.skill.yaml
- Backups and restore