lua sync compares your project with the agent on the server and resolves the differences, either interactively or with one flag per direction. Pulling writes local files; pushing updates the agent’s name, model, governance, and persona on the server. Primitive versions are reported but never pushed by this command.
Verified against lua-cli 3.33.0.
Synopsis
Description
Every run starts by compiling the project with server reconciliation: the server’s ids and active versions are written back intolua.skill.yaml, and any compiled primitive the agent does not have yet is registered on the server as an entity record with no version. This happens with --check too, so lua sync is not read-only on the server; a plain lua compile never contacts it. Registered but unversioned primitives show as not deployed in lua status.
The comparison covers the agent’s name, persona, model, and governance as written in src/index.ts and src/governance.ts, and the version of each skill, webhook, job, preprocessor, postprocessor, and active MCP server recorded in lua.skill.yaml against the active version on the server. A primitive drifts when the versions differ, when it exists only locally, or when it exists only on the server. Triggers, devices, voices, and workflows are not compared here; lua status covers them.
--check prints a summary and exits 1 with ✖ error: Operation failed when anything drifted. --pull takes the server’s side: for drifted source primitives it restores files from the latest source backup (recorded by lua push, including lua push backup), syncs MCP servers live into lua.skill.yaml, and then writes the server’s name, persona, and model into src/index.ts and its governance into src/governance.ts. Before writing, a conflict guard hashes every file the backup would overwrite; if any changed since your last backup it refuses, lists the files, and exits 1, unless you pass --force. Primitives that drifted but are absent from the backup are listed and make the command exit 1. --push takes your side for agent configuration only: it creates a persona version, which the agent serves from its next message, and updates the name, model, and governance, then lists drifted primitives with a hint to run lua push all --force. An absent local governance file is never pushed over a server policy; clear one with lua governance remove. --accept is an alias of --pull.
If a run aborts, lua.skill.yaml is restored to its pre-compile bytes so the next run detects the same drift.
Arguments
None.Options
Examples
Fail a CI job when the code and the server disagree; here the persona insrc/index.ts was edited after the last push:
Output
lua sync, whose per-item menu exits 1 under --ci; pass --check, --pull, or --push.
Take the server’s state, refusing if local files changed since the last backup:
src/index.ts, then push the primitives it reported:
✅ No drift detected. Local code is in sync with server. and exits 0.
Exit codes
See also
- Release an agent — where drift checks fit in a release
- Back up and restore source
lua status— per-primitive sync state without side effectslua pull— restore files from a specific backup or versionlua push— push primitive versions