Skip to main content

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.

​
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; lua source rollback restores any past version into your local workspace as a new version (history is append-only). 
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.
OptionDescription
--allShow all versions instead of the most recent 50.
--limit <n>Cap output at n versions. Default: 50.
lua source list                # most recent 50
lua source list --all          # full history
lua source list --limit 10     # cap at 10

​
lua source rollback

Downloads a past version’s files into your local workspace, then auto-pushes the rolled-back state as the next version.
OptionDescription
--version <n>Required. Version number to roll back to.
--forceSkip the confirmation prompt.
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. A schema change broke prod? lua source rollback --version <last-good> and you’re back.
  • Compare past versions. lua source list --all shows the timeline; pair with the admin dashboard 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.
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.

​
Common Workflow

# 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
  • Push Command — every push creates a new version
  • Sync Command — lua sync --pull restores the active version
  • Init Command — --restore-sources pulls the active version on first init