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. Compiles code - Ensures manifest is fresh (runs lua compile internally)
  2. Fetches server state - Gets the latest published persona and agent name from the server
  3. Compares with local - Checks your compiled manifest against server state
  4. Shows colored diff - Displays exactly what changed
  5. Prompts for action - Update local from server or keep local
New in v3.5.0: Sync now compiles before checking drift to ensure accurate comparison with the latest local changes.

​
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 opt-in during lua compile. By default, drift detection is disabled for faster compilation: 
lua compile        # Default: no drift check (fast)
lua compile --sync # Enable drift detection (checks before compiling)
This opt-in behavior is ideal for faster development iterations. Use --sync when you need to ensure alignment with the server.

​
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
--syncEnable drift detection during compile (checks before compiling)
--verboseShow detailed compilation output

​
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 with sync check (opt-in)
lua compile --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
      
      - name: Push version
        run: lua push skill --name mySkill --set-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: 
# Compile only (default - no drift check)
lua compile

# Compile with drift check
lua compile --sync

# Or push local changes to server before compile
lua sync --push && lua compile

​
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, compile runs without drift check by default (fast):
lua compile && lua push skill
Add --sync only if you need to validate against server state first.
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