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

# Source Command

> Inspect and roll back your agent's workspace source version history

## Overview

`lua source` manages your agent's workspace backup version history. Every `lua push` records the canonical state of your project. `lua source list` shows the version timeline. For rollback, prefer [`lua version promote`](/cli/version-command) — instant and atomic, no re-upload; `lua source rollback` (deprecated) remains available for restoring past source files into your workspace.

```bash theme={null}
lua source list                          # Recent 50 versions, active marked with *
lua source list --all                    # Full history
lua source rollback --version 5          # Restore v5 (with confirmation)
lua source rollback --version 5 --force  # Restore v5 (no prompt)
```

## Subcommands

### `lua source list`

Prints a table of source versions for the current agent, with the active version starred.

| Option        | Description                                      |
| ------------- | ------------------------------------------------ |
| `--all`       | Show all versions instead of the most recent 50. |
| `--limit <n>` | Cap output at `n` versions. Default: `50`.       |

```bash theme={null}
lua source list                # most recent 50
lua source list --all          # full history
lua source list --limit 10     # cap at 10
```

### `lua source rollback`

<Warning>
  **Deprecated for rollback.** With agent versioning, use [`lua version promote <version>`](/cli/version-command) instead — it swaps the live agent state instantly without re-uploading files. `lua source rollback` still works for restoring past *source files* into your workspace.
</Warning>

Downloads a past version's files into your local workspace, then auto-pushes the rolled-back state as the next version.

| Option          | Description                                   |
| --------------- | --------------------------------------------- |
| `--version <n>` | **Required.** Version number to roll back to. |
| `--force`       | Skip the confirmation prompt.                 |

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

## How Rollback Works

History is **append-only**. Rolling back to v5 does **not** overwrite v5 — instead:

1. The CLI downloads v5's files into your local workspace.
2. It then auto-pushes the rolled-back state, creating v(latest+1) with the same contents as v5.

You end up with an explicit new version at the head that represents "we returned to v5 on this date." The original v5 is preserved verbatim. This makes rollbacks safe — you can always roll back from your rollback.

```
Before: v1, v2, v3, v4, v5 (active)
        ↓ lua source rollback --version 2
After:  v1, v2, v3, v4, v5, v6 (active, contents = v2)
```

## When to Use

* **Recover from a bad push.** Prefer `lua version promote <last-good>` (instant). Use `lua source rollback --version <n>` only when you need the actual source files back in your workspace.
* **Compare past versions.** `lua source list --all` shows the timeline; pair with the [admin dashboard](/cli/utility-commands#admin) to diff.
* **Cross-machine recovery.** Lost your local workspace? `lua init --agent-id <id> --restore-sources` pulls the active version. Use `lua source rollback` to retrieve any other version.

<Warning>
  Rollback **overwrites your local workspace** with the chosen version's contents. If you have local edits you haven't pushed, push them first (or back them up) before rolling back.
</Warning>

## Common Workflow

```bash theme={null}
# Something is wrong in production — what changed recently?
lua source list

# Roll back to a known-good version
lua source rollback --version 12

# After investigation, re-apply your fix and push forward
# (the rollback created v13; your fix will push as v14)
lua push all --force
```

## Related

* [Push Command](/cli/skill-management#lua-push) — every `push` creates a new version
* [Sync Command](/cli/sync-command) — `lua sync --pull` restores the active version
* [Init Command](/cli/skill-management#lua-init) — `--restore-sources` pulls the active version on first init