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

> List the agent's source backup versions and restore one into the working copy

`lua source` lists the append-only history of source backups that `lua push` records for the agent, and restores one of them into your project. Nothing on this page changes what end users see; to change the live agent, promote an [agent version](/reference/cli/version).

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua source list [--all] [--limit <n>]
lua source rollback --version <n> [--force]
```

## Description

Every [`lua push`](/reference/cli/push), including `lua push backup`, stores a backup of your project files as source version `v<n>`; files are deduplicated by content, so only changed files are uploaded. `lua.skill.yaml` records the source version your working copy matches under `backup.activeVersion`, and `lua version create` links each agent version to the source version current at that moment.

`list` prints the most recent 50 source versions unless `--all` lifts the server cap; `--limit` caps how many of the returned rows are shown. The active version is marked `*`. Each row shows the version, creation time, creator, what triggered it (`batch push`, `rollback to v<n>`), and a shortened content hash.

`rollback --version <n>` downloads version `n`'s files, overwrites the working copy, and then records the result as `v<latest+1>` triggered by `rollback to v<n>`; no earlier version is modified. It asks `Rolling back to v<n> will overwrite local files and create a new version. Continue?` unless `--force` is passed, and the global `--ci` flag does not suppress the prompt. A rollback changes only your files and the backup history, not the live agent: promote an agent version to roll production back, and use rollback when you need the files themselves. The command always prints a deprecation warning pointing at `lua version promote` for that reason. [`lua pull --version <n>`](/reference/cli/pull) performs the same restore keyed by agent version instead of source version.

Both subcommands need a project and a credential.

## Arguments

| Argument   | Values             | Description                               |
| ---------- | ------------------ | ----------------------------------------- |
| subcommand | `list`, `rollback` | Required; `lua source` alone prints help. |

## Options

| Option          | Description                                                              | Default |
| --------------- | ------------------------------------------------------------------------ | ------- |
| `--all`         | `list`: fetch the full history instead of the server's most recent 50.   | off     |
| `--limit <n>`   | `list`: show at most `n` of the fetched versions.                        | `50`    |
| `--version <n>` | `rollback`: the source version to restore. Required; a positive integer. | none    |
| `--force`       | `rollback`: skip the confirmation prompt. Required in automation.        | off     |

## Examples

List recent source versions; the active one is marked `*`:

```bash theme={null}
lua source list --limit 3
```

```text Output theme={null}
VERSION   CREATED            BY        TRIGGERED BY                   HASH
v3 *	2026-09-12 12:49	user_…	batch push                    	8198f4f3...
v2	2026-09-12 12:29	user_…	batch push                    	41e603b3...
v1	2026-09-12 12:27	user_…	batch push                    	856f4be0...
```

Fetch the whole history and show up to 100 entries:

```bash theme={null}
lua source list --all --limit 100
```

Restore the files from source version 2 and record them as a new version, without a prompt:

```bash theme={null}
lua source rollback --version 2 --force --ci
```

Push the restored files and promote a version if you want them live:

```bash theme={null}
lua push all --force
lua version create -m "Restore source v2"
lua version promote <n>
```

## Exit codes

| Code | Meaning                                                                                                                                                                                                        |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Listed, restored, or the prompt was declined. `list` outside a project also exits 0 after printing `No agentId in lua.skill.yaml. Run `lua init` first.`                                                       |
| `1`  | `--version must be a positive integer`, `rollback` outside a project, the version does not exist, the download or backup push failed, or any other refusal from the backup API, reported as `HTTP <status> …`. |
| `9`  | No credential.                                                                                                                                                                                                 |
| `11` | The server or network is unavailable.                                                                                                                                                                          |

## See also

* [Back up and restore source](/ship/backups-and-restore)
* [`lua pull`](/reference/cli/pull) — restore by agent version
* [`lua version`](/reference/cli/version) — promote to change what is live
* [`lua.skill.yaml`](/reference/cli/lua-skill-yaml) — the `backup` section