Sync Command

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

Component	Description
Name	Agent name defined in `LuaAgent({ name: "..." })`
Persona	Agent persona defined in `LuaAgent({ persona: "..." })`

How It Works

Compiles code - Ensures manifest is fresh (runs lua compile internally)
Fetches server state - Gets the latest published persona and agent name from the server
Compares with local - Checks your compiled manifest against server state
Shows colored diff - Displays exactly what changed
Prompts for action - Update local from server or keep local

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

Flag	Description
`--check`	Check for drift only, exit code 1 if drift found (CI validation)
`--pull`	Pull server state to local without prompting. Source files are restored from the snapshot.
`--accept`	Deprecated alias for `--pull` — kept for backwards compatibility. New scripts should use `--pull`.
`--push`	Push local changes to server without prompting
`--force`	Skip the local-changes conflict check (use with `--pull` / `--accept`). Destructive — overwrites local changes.

Compile Integration

Flag	Description
`--sync`	Enable drift detection during compile (checks before compiling)
`--verbose`	Show detailed compilation output

Non-Interactive Mode

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

# Pull server state to local without prompting
lua sync --pull

# Pull and bypass the local-changes conflict guard (destructive)
lua sync --pull --force

# 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

# Pull server state to local
lua sync --pull

# 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

Run sync before starting work

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

Use sync --accept for fresh pulls

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.

Fast CI/CD builds

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.

Commit after syncing

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 Type	Description	Used for Sync?
Draft	Created but not deployed	❌ No
Published	Has been deployed at least once	✅ Yes (latest)
Current	Currently 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

✅ No drift detected. Local code is in sync with server.

Your local code matches the server. No action needed.

Network error

If the server is unreachable, sync will silently continue to avoid blocking your workflow.

No persona on server

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

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

What Gets Synced

How It Works

Usage

Interactive Sync

During Compile

Options

Sync Command Options

Compile Integration

Non-Interactive Mode

Examples

CI/CD Workflow Example

Common Scenarios

Scenario 1: Someone Updated Persona in Dashboard

Scenario 2: Forgot to Push Changes

Scenario 3: CI/CD Pipeline

Best Practices

How Server Versions Work

Error Handling

lua compile

lua push persona

lua persona

​Overview

​What Gets Synced

​How It Works

​Usage

​Interactive Sync

​During Compile

​Options

​Sync Command Options

​Compile Integration

​Non-Interactive Mode

​Examples

​CI/CD Workflow Example

​Common Scenarios

​Scenario 1: Someone Updated Persona in Dashboard

​Scenario 2: Forgot to Push Changes

​Scenario 3: CI/CD Pipeline

​Best Practices

​How Server Versions Work

​Error Handling

​Related Commands

lua compile

lua push persona

lua persona

Overview

What Gets Synced

How It Works

Usage

Interactive Sync

During Compile

Options

Sync Command Options

Compile Integration

Non-Interactive Mode

Examples

CI/CD Workflow Example

Common Scenarios

Scenario 1: Someone Updated Persona in Dashboard

Scenario 2: Forgot to Push Changes

Scenario 3: CI/CD Pipeline

Best Practices

How Server Versions Work

Error Handling

Related Commands