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

> Restore the project's source files from the latest backup or from the backup linked to an agent version

`lua pull` overwrites the files in your project with a source backup stored on the server, either the most recent one or the one linked to an agent version, and records the restored state as a new source version. It changes nothing for end users.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua pull [--version <n>] [--force]
```

## Description

Every [`lua push`](/reference/cli/push) records a backup of your project files as a numbered source version (see [`lua source`](/reference/cli/source)), and every [agent version](/reference/cli/version) links to the source version that was current when it was created. Without flags, `lua pull` restores the latest source version. With `--version <n>`, it looks up agent version `n` and restores the source version linked to it; a version without a linked backup fails with `Version v<n> has no source backup linked. Cannot pull source for this version.`

The restore downloads the backed-up files and overwrites the working copy. It then records the result as a new source version, so the history stays append-only and `lua source list` shows a new entry after every pull. Files that exist locally but not in the backup are left in place.

Before writing, the command asks `Rolling back to v<n> will overwrite local files and create a new version. Continue?` unless you pass `--force`. The global `--ci` flag does not suppress this prompt, so automation must pass `--force`. Unlike [`lua sync --pull`](/reference/cli/sync), `lua pull` performs no local-changes check: edits in files the backup contains are lost. Commit them, or run `lua push backup` first so they become the latest backup.

With [`lua git connect`](/reference/cli/git) enabled, the restored files are committed automatically. The command needs a project and a credential. Pulling never changes what is live; to change the live agent, promote a version with `lua version promote`.

## Arguments

None.

## Options

| Option          | Description                                                       | Default              |
| --------------- | ----------------------------------------------------------------- | -------------------- |
| `--version <n>` | Agent version whose linked source backup to restore; `3` or `v3`. | latest source backup |
| `--force`       | Skip the confirmation prompt. Required in automation.             | off                  |

## Examples

Restore the most recent backup, for example on a fresh machine after `lua init --agent-id <id>`:

```bash theme={null}
lua pull
```

Check out the exact source behind agent version 3 before deciding whether to promote it:

```bash theme={null}
lua pull --version 3
lua version promote 3
```

Restore without a prompt, in a script:

```bash theme={null}
lua pull --version v3 --force --ci
```

The command prints which backup it restores, `Pulling latest source backup (v<n>)…` or `Pulling source for agent version v<n> (backup v<m>)…`, followed by the backup push that records the new source version.

## Exit codes

| Code | Meaning                                                                                                                     |
| ---- | --------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Files restored and recorded as a new source version, or the prompt was declined.                                            |
| `1`  | `No backup versions available to pull.`, the agent version does not exist, it has no linked backup, or the download failed. |
| `2`  | Not inside a project, or no agent configured in `lua.skill.yaml`.                                                           |
| `9`  | No credential, or the server rejected it.                                                                                   |
| `11` | The server or network is unavailable.                                                                                       |

## See also

* [Back up and restore source](/ship/backups-and-restore)
* [`lua source`](/reference/cli/source) — list source versions and restore by source number
* [`lua version`](/reference/cli/version) — agent versions and the promote path
* [`lua sync`](/reference/cli/sync) — guarded pull of drifted primitives only