---
title: Sync Commands
description: "Commands for cloud synchronization and authentication"
---

# Sync Commands

Commands for syncing with the Kernle cloud backend and managing authentication.

## sync

Synchronize memory with the remote backend.

### sync status

Check sync status, pending operations, and connection.

```bash
kernle -a <agent> sync status [--json]
```

**Example output:**
```
Sync Status
===========
Backend: https://api.kernle.ai
Agent: claire
User: user_abc123

Pending: 3 operations
Last Push: 2024-01-15 14:32:00
Last Pull: 2024-01-15 14:30:00
Status: Connected
```

### sync push

Push pending local changes to remote.

```bash
kernle -a <agent> sync push [--limit L] [--json]
```

| Option | Description |
|--------|-------------|
| `-l, --limit L` | Maximum operations to push (default: all) |

```bash
# Push all pending changes
kernle -a claire sync push

# Push up to 10 changes
kernle -a claire sync push --limit 10
```

### sync pull

Pull remote changes to local.

```bash
kernle -a <agent> sync pull [--full] [--json]
```

| Option | Description |
|--------|-------------|
| `-f, --full` | Pull all records (not just since last sync) |

```bash
# Pull recent changes
kernle -a claire sync pull

# Full sync from cloud
kernle -a claire sync pull --full
```

### sync full

Full bidirectional sync (pull then push).

```bash
kernle -a <agent> sync full [--json]
```

```bash
kernle -a claire sync full
```

---

## auth

Authentication and credentials management.

### auth register

Register for cloud sync with email.

```bash
kernle -a <agent> auth register [--email EMAIL] [--backend-url URL] [--json]
```

```bash
kernle -a claire auth register --email user@example.com
```

This will:
1. Send a verification email
2. Create your account on the backend
3. Store credentials locally in `~/.kernle/credentials.json`

### auth login

Log in with an API key.

```bash
kernle -a <agent> auth login [--api-key KEY] [--backend-url URL] [--json]
```

```bash
# Interactive login
kernle -a claire auth login

# With API key
kernle -a claire auth login --api-key knl_sk_xxxxx
```

### auth status

Check authentication status.

```bash
kernle -a <agent> auth status [--json]
```

**Example output:**
```
Authentication Status
=====================
Backend: https://api.kernle.ai
Authenticated: Yes
User ID: user_abc123
Agent: claire
API Keys: 2 active
```

### auth logout

Log out and clear credentials.

```bash
kernle -a <agent> auth logout [--json]
```

### auth keys

Manage API keys.

#### List Keys

```bash
kernle auth keys list [--json]
```

#### Create Key

```bash
kernle auth keys create [--name NAME] [--json]
```

```bash
kernle auth keys create --name "Development Machine"
```

#### Revoke Key

```bash
kernle auth keys revoke KEY_ID [--force] [--json]
```

| Option | Description |
|--------|-------------|
| `--force` | Skip confirmation prompt |

#### Cycle Key

Generate a new key and deactivate the old one.

```bash
kernle auth keys cycle KEY_ID [--force] [--json]
```

---

## Auto-Sync Configuration

Kernle can automatically sync during `load` and `checkpoint save` operations.

### Enable Auto-Sync

Auto-sync is enabled by default when credentials are configured. Control it with flags:

```bash
# Force sync on load
kernle -a claire load --sync

# Skip sync on load
kernle -a claire load --no-sync

# Force sync after checkpoint
kernle -a claire checkpoint save "task" --sync

# Skip sync after checkpoint
kernle -a claire checkpoint save "task" --no-sync
```

### Sync Architecture

<Info>
**Local-First with Sync Queue**

1. All changes written to local SQLite first
2. Changes queued in `sync_queue` table
3. Queue deduplicates by `(table, record_id)`
4. Push to cloud when online
5. Pull remote changes on `load()` if auto_sync enabled
</Info>

### Conflict Resolution

Kernle uses a hybrid conflict resolution strategy:

- **Scalar fields**: Last-write-wins based on `local_updated_at` timestamp
- **Array fields**: Set union (merge) to preserve data from both sides

This means when conflicts occur, you never lose tags, lessons, or other array data that was added on either device.

#### Array Fields That Are Merged

| Table | Merged Fields |
|-------|---------------|
| `episodes` | `lessons`, `tags`, `emotional_tags`, `source_episodes`, `derived_from`, `context_tags` |
| `beliefs` | `source_episodes`, `derived_from`, `context_tags` |
| `notes` | `tags`, `source_episodes`, `derived_from`, `context_tags` |
| `drives` | `focus_areas`, `source_episodes`, `derived_from`, `context_tags` |
| `agent_values` | `source_episodes`, `derived_from`, `context_tags` |
| `relationships` | `source_episodes`, `derived_from`, `context_tags` |
| `goals` | `source_episodes`, `derived_from`, `context_tags` |
| `playbooks` | `trigger_conditions`, `failure_modes`, `recovery_steps`, `source_episodes`, `tags` |

<Warning>
**Array Size Limit**: Merged arrays are capped at 500 items to prevent resource exhaustion. If a merge exceeds this limit, the array is truncated with a warning logged.
</Warning>

#### How Merging Works

**Example**: Local has `tags=["A", "B"]` and cloud has `tags=["B", "C"]`

- If cloud timestamp is newer: Cloud wins for scalar fields, but merged `tags=["A", "B", "C"]`
- If local timestamp is newer: Local wins for scalar fields, but merged `tags=["A", "B", "C"]`

Conflicts are recorded with resolution types:
- `cloud_wins_arrays_merged` - Cloud was newer, arrays merged from local
- `local_wins_arrays_merged` - Local was newer, arrays merged from cloud

### Offline Mode

Kernle works fully offline. Changes are queued and synced when connectivity returns:

```bash
# Check pending operations
kernle -a claire sync status

# Push when back online
kernle -a claire sync push
```
