> ## 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.
# Sync Command
> Detect and resolve drift between server state and local code
## Overview
The `lua sync` command detects differences (drift) between your server-deployed configuration and local code, helping you keep them in sync.
```bash theme={null}
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
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
Sync now compiles before checking drift to ensure accurate comparison with the latest local changes.
## Usage
### Interactive Sync
```bash theme={null}
lua sync
```
If drift is detected, you'll see a colored diff:
```
============================================================
PERSONA DIFF
- Server (deployed) + Local (code)
============================================================
- Old Agent Name
+ New Agent Name
... (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:
```bash theme={null}
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
```bash theme={null}
# 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
```bash theme={null}
# 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
```yaml theme={null}
# 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.
```bash theme={null}
$ lua sync
⚠️ Drift detected!
============================================================
PERSONA DIFF
- Server (deployed) + Local (code)
============================================================
- Updated persona from dashboard
+ Your local persona version
? 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.
```bash theme={null}
$ 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:
```bash theme={null}
# 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.
```bash theme={null}
cd my-agent
lua sync # Check for drift
lua compile # Start development
```
When you want to ensure you have the latest server state:
```bash theme={null}
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):
```bash theme={null}
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:
```bash theme={null}
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. 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.
## Related Commands
Compile with optional sync check
Push persona to server
Manage persona in sandbox/production