Skip to main content

​
Overview

The lua sync command detects differences (drift) between your server-deployed configuration and local code, helping you keep them in sync. 
lua sync
The sync command helps prevent accidental overwrites when someone updates the agent from the admin dashboard while you’re working locally.

​
What Gets Synced

ComponentDescription
NameAgent name defined in LuaAgent({ name: "..." })
PersonaAgent persona defined in LuaAgent({ persona: "..." })

​
How It Works

  1. Fetches server state - Gets the latest published persona and agent name from the server
  2. Compares with local - Checks your src/index.ts LuaAgent configuration
  3. Shows colored diff - Displays exactly what changed
  4. Prompts for action - Update local from server or keep local

​
Usage

​
Interactive Sync

lua sync
If drift is detected, you’ll see a colored diff: 
============================================================
PERSONA DIFF
- Server (deployed)  + Local (code)
============================================================

  <persona>
    <identity>
-     Old Agent Name
+     New Agent Name
    </identity>
  ... (unchanged lines) ...

============================================================

? What would you like to do with persona?
❯ 📥 Update local from server
  ⏭️  Skip (keep local)
Diff colors:
  • 🔴 Red (-) = Line exists on server but not in local code
  • 🟢 Green (+) = Line exists in local code but not on server
  • Gray = Unchanged lines (abbreviated if many)

​
During Compile

Sync is automatically checked during lua compile: 
lua compile           # Checks for drift, prompts if found
lua compile --no-sync # Skip sync check
lua compile --force-sync # Auto-update from server without prompting

​
Options

​
Compile Integration

FlagDescription
--no-syncSkip drift detection during compile
--force-syncAutomatically update local from server if drift detected

​
Examples

# Check for drift interactively
lua sync

# Compile without sync check (useful for CI/CD)
lua compile --no-sync

# Auto-sync before compile (useful for pulling latest)
lua compile --force-sync

​
Common Scenarios

​
Scenario 1: Someone Updated Persona in Dashboard

You’re developing locally, and a colleague updated the persona from the admin dashboard. 
$ lua sync
⚠️  Drift detected!

============================================================
PERSONA DIFF
- Server (deployed)  + Local (code)
============================================================

  <persona>
-   Updated persona from dashboard
+   Your local persona version
  </persona>

? What would you like to do with persona?
❯ 📥 Update local from server   # Get their changes
  ⏭️  Skip (keep local)         # Keep yours (will overwrite on next push)

​
Scenario 2: Forgot to Push Changes

You made changes locally but forgot to push before reverting your code. 
$ lua sync
✅ No drift detected. Local code is in sync with server.

​
Scenario 3: CI/CD Pipeline

In your deployment pipeline, you might want to ensure no drift: 
# Will exit with error if drift exists (user must resolve manually)
lua compile

# Or skip sync in CI (push will overwrite server)
lua compile --no-sync

​
Best Practices

Always run lua sync when starting a new session to catch any changes made by teammates or from the dashboard.
cd my-agent
lua sync           # Check for drift
lua compile        # Start development
When you want to ensure you have the latest server state:
lua compile --force-sync
This automatically updates your local code without prompting.
In automated pipelines where you want your code to be the source of truth:
lua compile --no-sync && lua push skill
After syncing from server, commit the changes to preserve them:
lua sync
# Select "Update local from server"
git add src/index.ts
git commit -m "sync: update persona from server"

​
How Server Versions Work

The sync command compares against the latest published persona version, not the currently active one:
Version TypeDescriptionUsed for Sync?
DraftCreated but not deployed❌ No
PublishedHas been deployed at least once✅ Yes (latest)
CurrentCurrently active in production❌ No
This means if you roll back to an older version in production, sync will still compare against the most recent push (not the rollback).

​
Error Handling

✅ No drift detected. Local code is in sync with server.
Your local code matches the server. No action needed.
If the server is unreachable, sync will silently continue to avoid blocking your workflow.
If no persona has been pushed to the server yet, sync will report no drift.

lua compile

Compile with optional sync check

lua push persona

Push persona to server

lua persona

Manage persona in sandbox/production