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?
❯ 📤 Push local to server
  📥 Pull server to local
  ⏭️  Skip
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. By default, drift detection is non-blocking - it warns about drift but continues compilation: 
lua compile           # Checks for drift, warns if found, continues
lua compile --no-sync # Skip drift check entirely (silent)
This non-blocking default is ideal for automated workflows (CI/CD, AI agents, Cursor).

​
Options

​
Sync Command Options

FlagDescription
--checkCheck for drift only, exit code 1 if drift found (CI validation)
--acceptAuto-accept server state without prompting (pull from server)
--pushPush local changes to server without prompting

​
Compile Integration

FlagDescription
--no-syncSkip drift detection entirely during compile

​
Non-Interactive Mode

# Check for drift only (returns exit code 1 if drift detected)
lua sync --check

# Auto-pull server state to local without prompting
lua sync --accept

# Auto-push local changes to server without prompting
lua sync --push

​
Examples

# Check for drift interactively
lua sync

# Check only, fail if drift (for CI)
lua sync --check

# Auto-accept server state (pull)
lua sync --accept

# Auto-push local changes to server
lua sync --push

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

​
CI/CD Workflow Example

# GitHub Actions example
name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check for drift
        run: lua sync --check
      
      - name: Compile
        run: lua compile --no-sync
      
      - name: Push version
        run: lua push skill --name mySkill --version ${{ github.sha }} --force
      
      - name: Deploy to production
        run: lua deploy --skill-name mySkill --skill-version latest --force

​
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?
  📤 Push local to server   # Overwrite server with your version
❯ 📥 Pull server to local   # Get their changes
  ⏭️  Skip                  # No changes

​
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 or push local as source of truth: 
# Check for drift, warn but continue (default behavior)
lua compile

# Skip sync entirely in CI
lua compile --no-sync

# Or push local changes to server before compile
lua sync --push && 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 sync --accept
This automatically updates your local code from the server 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