> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# lua push

> Push a new version of one primitive, or stage every primitive, the agent configuration, and a source backup

`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`](/reference/cli/version), [`lua deploy`](/reference/cli/deploy), or `lua workflows deploy`.

*Requires lua-cli 3.36.0 or later.*

## Synopsis

```bash theme={null}
lua push
lua push all --force [--no-include-source]
lua push <type> [--name <name>] [--set-version <ver>] [--force] [--auto-deploy] [--no-include-source]
lua push agent [--force] [--auto-deploy]
lua push webapp [--name <name>] [--set-version <ver>] [--force] [--auto-deploy]
lua push backup [--force] [--fresh]
```

## Description

Every form except `backup` starts with a compile that also reconciles [`lua.skill.yaml`](/reference/cli/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. 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](/concepts/releases-and-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, trigger, or web app it creates and promotes a scoped agent version (see [`lua deploy`](/reference/cli/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](/concepts/persona) version when the code has persona text, pushes the [model](/concepts/models) 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. From lua-cli 3.49.0 it deploys like the other single primitives: `--auto-deploy` makes the version live on its own (see [`lua deploy`](/reference/cli/deploy)), the question after the push offers the same, and without either the command ends with `Staged but NOT live yet` and the `lua deploy webapp` step. An [agent version](/concepts/releases-and-versions) that pins the web app makes it live too. On lua-cli 3.42 to 3.48 it never asks, `--auto-deploy` does nothing, and a web-app version goes live only with the agent version that pins it. 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](/build/apps/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](/integrations/custom-mcp-servers) 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`](/reference/cli/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`](/reference/cli/workflows); `lua deploy` has no `workflow` type. `lua push browser --name <name>` creates or updates one [named browser](/reference/sdk/browser#named-browsers) 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

| Argument | Values | Description |
| - | - | - |
| `type` | `skill`, `agent`, `webhook`, `trigger`, `job`, `preprocessor`, `postprocessor`, `mcp`, `device`, `device-trigger`, `voice`, `workflow`, `webapp`, `browser`, `backup`, `all` | Omitted: stage everything. Aliases: `persona` for `agent`, plurals, `web-app` for `webapp`, `pre`, `post`, `pp`, `hook`, `mcp-server`, `everything` for `all` |

## Options

| Option | Description | Default |
| - | - | - |
| `--name <name>` | Entity to push; requires a type | prompt, or the only entity |
| `--set-version <ver>` | Version to push, for example `1.0.5`; must start with `major.minor.patch` | next patch |
| `--force` | No prompts: auto-bump the version and skip the deploy question. Required by `all` | prompt |
| `--auto-deploy` | Single primitive (`webapp` from lua-cli 3.49.0): deploy after pushing; `agent`: activate the persona version just staged; `mcp`: activate. Ignored for bare `push` and `all` | ask |
| `--no-include-source` | Skip attaching project source to skill versions | attach |
| `--fresh` | `backup` only: build the backup from disk instead of the last compile | compiled manifest |
| `--apply-effort` | `workflow` only: mark the pushed version so that each agent step's `effort` is sent to the model from this version on, where the platform forwards it; a plain push never sends it. Prints `⚙️  --apply-effort: "<name>" is pushed with per-step effort ENABLED` before the push. Runs in flight and earlier versions are unaffected; see [Author a workflow](/build/workflows/authoring#choose-a-model-per-step) | estimate-only |

## Examples

Stage everything, then create and promote an agent version:

```bash theme={null}
lua push
lua version create -m "ticket escalation"
lua version promote <n>
```

Stage everything from a script; progress goes to stderr and the result to stdout:

```bash theme={null}
lua push --ci
```

```text Output theme={null}
✅ Compiled 8 primitives (1 agent, 1 skill, 3 tools, 1 webhook, 1 preprocessor, 1 postprocessor) in 546ms
  📝 tickets: 1.0.3 → 1.0.4
  ✅ tickets v1.0.4 pushed
  📝 ticket-status-webhook: 1.0.3 → 1.0.4
  ✅ ticket-status-webhook v1.0.4 pushed
…
  ✅ Persona version 4 created
  ✅ Model "alibaba/qwen3.8-flash" pushed
…
💾 Backup at v4 (1 new file(s))

✅ Push All Complete!
…
Run `lua version create [-m "<message>"]` to snapshot the staged state into a named version, then `lua version promote <n>` to deploy.
```

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:

```bash theme={null}
lua push --ci > push.log 2>&1 || exit $?
! grep -q 'component(s) failed to push' push.log
```

Push one skill at an explicit version without prompts and make it live (on a versioned agent the next `lua version promote` resets it):

```bash theme={null}
lua push skill --name tickets --set-version 1.1.0 --force --auto-deploy --ci
```

Push the persona and model from `src/index.ts`:

```bash theme={null}
lua push agent --force --ci
```

Build and stage a web app, then make it live with an agent version:

```bash theme={null}
lua push webapp --name ops-dashboard --force --ci
lua version create -m "ops dashboard"
lua version promote <n>
```

Push a workflow and fail if any `env()` key is unset in production:

```bash theme={null}
LUA_PUSH_ENV_CHECK=error lua push workflow --name outreach --force --ci
```

Recover the source backup after a push reported `Source backup failed`:

```bash theme={null}
lua push backup --force --fresh --ci
```

## Exit codes

| Code | When |
| - | - |
| `0` | Pushed; bare `push` and `all` also exit 0 when some items failed |
| `1` | `compile_failed`; version refused; `--name` without a type; an invalid `--set-version`; `all` without `--force`; no agent configuration; backup failed |
| `2` | Unknown type |
| `3` | The file's id for the entity no longer exists on the server |
| `9` | No credential, or the platform refused it |
| `10` | The credential may not push to this agent |
| `11` | Platform or network unavailable |

## See also

* [Release an agent](/ship/releasing) — push, version create, promote
* [`lua version`](/reference/cli/version) and [`lua deploy`](/reference/cli/deploy)
* [lua.skill.yaml](/reference/cli/lua-skill-yaml)
* [Backups and restore](/ship/backups-and-restore)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.