lua push uploads a source backup: an append-only, content-addressed copy of the project files, numbered v1, v2, and so on. An agent version records which source backup it was created from, so lua pull --version <n> returns the code behind a release. Backups are not a substitute for git; see Keep a git history.
Verified against lua-cli 3.33.0.
Before you begin
- A project signed in with
lua auth configureand an agent ID inlua.skill.yaml. - For a restore on a new machine: the agent ID (from
lua agentsor the admin dashboard) and an empty directory.
1
Push a backup explicitly
lua push all and every single-primitive push run the backup automatically. Run it on its own after edits you have not pushed, such as a README change.--fresh walks the disk instead of trusting the last compile, so it captures files a compile never saw; --force skips the freshness guard that refuses to overwrite a newer backup pushed from another machine. A backup includes every project file except node_modules, dist, dist-v2, .git, .lua, .temp, coverage, .next, and .turbo directories, dotfiles (so .env is never backed up), lockfiles, test files (*.test.*, *.spec.*, __tests__), .d.ts and .map files, and any file over 256 KB. src/ is stored in full on Lua’s servers, a webhook’s secret literal included; nothing deletes a backup (a pull or rollback appends a new version), and any credential with agents:read on the agent can download one. The result is recorded in lua.skill.yaml:lua.skill.yaml
2
List backup versions
Each version records who created it, what triggered it, and a hash of the project contents; The list shows the most recent 50;
* marks the version your checkout last pushed or restored.Output
--all fetches the full history (lua source reference).3
Restore a project on a new machine
lua init for an existing agent in an empty directory downloads the latest backup, writes lua.skill.yaml, and installs dependencies. --restore-sources answers the overwrite prompt so the command runs unattended.lua init says so (No backup on file for this agent.) and scaffolds a fresh project instead; push from the original machine first (lua init reference).4
Pull a backup into an existing checkout
lua pull overwrites local files with the latest backup; --version <n> takes an agent version number and restores the source that version was created from.5
Roll source back to an earlier backup
lua source rollback restores backup v<n> locally and records it as v<latest+1>; history is never rewritten. It changes files on disk only: what runs in production is still the promoted agent version, which you change with lua version promote.lua version promote; use lua pull --version <n> when you want the source of a specific release.6
Verify
Confirm the new version is the active one and that the checkout matches it.
backup.status is synced when the files on disk match the last pushed backup, out-of-sync when they differ, and never-compiled before the first compile.Options you may need
Find the backup behind an agent version
lua version create requires a backup and fails with No backup exists for this agent. Run `lua push` first, or pass `--auto-push` to push and snapshot in one step. when there is none. lua version list --json and lua version show <n> --json include sourceManifestVersion, the backup number behind each agent version, and lua pull --version <n> refuses a version with none linked (Version v<n> has no source backup linked.).
Keep a git history
lua git connect turns on auto-commits: after each lua push, lua version create|promote|delete, and lua pull, the CLI commits the working tree and tags version snapshots as lua/v<n>. It requires a git repository with user.name and user.email set and never runs git init for you. --auto-push additionally pushes to a GitHub HTTPS origin once you link an account with lua git auth github. lua git disconnect turns it off and leaves existing commits alone (lua git reference).
If it isn’t working
❌ Refusing to push backup — server has a different backup than this machine's last push:
❌ Refusing to push backup — server has a different backup than this machine's last push:
Another machine pushed after your last push. Run
lua sync --pull to take the server’s files first, or lua push backup --force to replace the server backup with yours (the other machine’s changes remain in history as an earlier version).❌ Refusing to pull — <n> local file(s) have uncommitted changes since your last push
❌ Refusing to pull — <n> local file(s) have uncommitted changes since your last push
lua sync --pull found files changed since your last backup. Save them with lua push backup, or pass --force to overwrite them.✖ error: No backup versions available to pull.
✖ error: No backup versions available to pull.
The agent has never been pushed from the CLI. Run
lua push backup --force --fresh on the machine that has the source, then pull again.Next steps
Release an agent to production
How agent versions are created and promoted.
lua sync reference
Drift detection and the
--pull conflict guard.lua pull reference
Restore the latest backup or a version’s source.
About security and data
What a backup stores and what it never includes.