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

*Verified against lua-cli 3.33.0.*

## 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 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. 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](/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, or trigger 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 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`](/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.

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`, `backup`, `all` | Omitted: stage everything. Aliases: `persona` for `agent`, plurals, `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: deploy after pushing; `agent`: deploy the persona version; `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          |

## 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
```

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)