spacedrive/docs/cli/library-sync-setup.mdx

# CLI: Library Sync Setup Commands

## Overview

After pairing two devices, use these commands to set up library synchronization between them.

## Prerequisites

1. **Devices must be paired** - Use `sd network pair generate` and `sd network pair join` first
2. **At least one library exists** - Use `sd library list` to see available libraries
3. **Networking must be running** - Check with `sd network status`
4. **Know the device IDs** - Use `sd network devices` to list paired devices

## Commands

### 0. List Paired Devices (Get Device IDs)

First, you need to know the device ID of the paired device.

```bash
sd network devices
```

**Options**:
- `--connected` - Show only currently connected devices

**Example**:
```bash
$ sd network devices

Paired Devices (2 total, 1 connected):
─────────────────────────────────────────────────────

  Name: Bob's MacBook
  ID: 550e8400-e29b-41d4-a716-446655440000
  Type: Desktop
  OS Version: 1.0
  App Version: 2.0.0
  Status: Connected
  Last Seen: 2025-10-05 03:30:00

  Name: Alice's iPhone
  ID: e1054ba9-2e8b-4847-9644-a7fb764d4221
  Type: Mobile
  OS Version: 1.0
  App Version: 2.0.0
  Status: Paired
  Last Seen: 2025-10-04 18:45:00
```

**JSON Output**:
```bash
$ sd network devices --output json
{
  "devices": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Bob's MacBook",
      "device_type": "Desktop",
      "os_version": "1.0",
      "app_version": "2.0.0",
      "is_connected": true,
      "last_seen": "2025-10-05T03:30:00Z"
    }
  ],
  "total": 2,
  "connected": 1
}
```

**Filter Connected Only**:
```bash
$ sd network devices --connected

Paired Devices (1 total, 1 connected):
─────────────────────────────────────────────────────

  Name: Bob's MacBook
  ID: 550e8400-e29b-41d4-a716-446655440000
  Status: Connected
```

### 1. Discover Remote Libraries

Discover what libraries are available on a paired device.

```bash
sd library sync-setup discover <DEVICE_ID>
```

**Arguments**:
- `<DEVICE_ID>` - UUID of the paired device

**Example**:
```bash
$ sd library sync-setup discover 550e8400-e29b-41d4-a716-446655440000

Device: Bob's MacBook (550e8400-e29b-41d4-a716-446655440000)
Online: true

Remote Libraries (2):
─────────────────────────────────────────

  Name: My Library
  ID: 3f8cb26f-de79-4d87-88dd-01be5f024041
  Created: 2025-01-01 10:30:00
  Entries: 5000
  Locations: 3
  Devices: 1
  Size: 10737418240 bytes

  Name: Work Documents
  ID: 7a9c2d1e-5f84-4b23-a567-1234567890ab
  Description: Work files and projects
  Created: 2025-01-15 14:20:00
  Entries: 1200
  Locations: 2
  Devices: 1
  Size: 2147483648 bytes
```

**JSON Output**:
```bash
$ sd library sync-setup discover <DEVICE_ID> --output json
{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_name": "Bob's MacBook",
  "is_online": true,
  "libraries": [
    {
      "id": "3f8cb26f-de79-4d87-88dd-01be5f024041",
      "name": "My Library",
      "description": null,
      "created_at": "2025-01-01T10:30:00Z",
      "statistics": {
        "total_entries": 5000,
        "total_locations": 3,
        "total_size_bytes": 10737418240,
        "device_count": 1
      }
    }
  ]
}
```

### 2. Setup Library Sync

Configure library sync between local and remote devices.

```bash
sd library sync-setup setup \
  --local-library <LOCAL_LIBRARY_ID> \
  --remote-device <REMOTE_DEVICE_ID> \
  [--remote-library <REMOTE_LIBRARY_ID>] \
  [--action <ACTION>] \
  [--leader <LEADER>] \
  [--local-device <LOCAL_DEVICE_ID>]
```

**Required Arguments**:
- `--local-library` - UUID of your local library
- `--remote-device` - UUID of the paired device

**Optional Arguments**:
- `--remote-library` - UUID of the remote library to sync with (optional for register-only)
- `--action` - Sync action type (default: `register-only`)
  - `register-only` - Just register devices (Phase 1) 
  - `merge-into-local` - Future (Phase 3)
  - `merge-into-remote` - Future (Phase 3)
  - `create-shared` - Future (Phase 3)
- `--leader` - Which device is the sync leader (default: `local`)
  - `local` - This device is the leader
  - `remote` - Remote device is the leader
- `--local-device` - Override auto-detected local device ID

**Example**:
```bash
$ sd library sync-setup setup \
  --local-library 3f8cb26f-de79-4d87-88dd-01be5f024041 \
  --remote-device 550e8400-e29b-41d4-a716-446655440000 \
  --remote-library 7a9c2d1e-5f84-4b23-a567-1234567890ab \
  --action register-only \
  --leader local

✓ Library sync setup successful
  Local library: 3f8cb26f-de79-4d87-88dd-01be5f024041
  Remote library: 7a9c2d1e-5f84-4b23-a567-1234567890ab
  Devices successfully registered for library access
```

## Complete Workflow Example

Here's a complete workflow for pairing devices and setting up library sync:

### Device A (CLI Daemon)

```bash
# 1. Start the daemon
$ sd start --foreground

# 2. Generate a pairing code
$ sd network pair generate
Pairing code: word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12
Session: 2369763d-e205-a344-6341-dbfa2ec8a709
Expires at: 2025-10-05 03:28:44

# 3. Wait for Device B to join...
# (Pairing completes)

# 4. List paired devices (get device IDs)
$ sd network devices

Paired Devices (1 total, 1 connected):
─────────────────────────────────────────────────────

  Name: iOS Device
  ID: e1054ba9-2e8b-4847-9644-a7fb764d4221
  Type: Mobile
  Status: Connected

# 5. List local libraries
$ sd library list
- 3f8cb26f-de79-4d87-88dd-01be5f024041 /Users/alice/Library/Application Support/spacedrive/libraries/My Library.sdlibrary

# 6. Discover libraries on Device B (iOS)
$ sd library sync-setup discover e1054ba9-2e8b-4847-9644-a7fb764d4221
Device: iOS Device (e1054ba9-2e8b-4847-9644-a7fb764d4221)
Online: true

Remote Libraries (1):
─────────────────────────────────────────

  Name: My Library
  ID: d9828b35-6618-4d56-a37a-84ef03617d1e
  Entries: 0
  Locations: 0
  Devices: 1

# 7. Set up library sync
$ sd library sync-setup setup \
  --local-library 3f8cb26f-de79-4d87-88dd-01be5f024041 \
  --remote-device e1054ba9-2e8b-4847-9644-a7fb764d4221 \
  --remote-library d9828b35-6618-4d56-a37a-84ef03617d1e \
  --leader local

✓ Library sync setup successful
  Local library: 3f8cb26f-de79-4d87-88dd-01be5f024041
  Remote library: d9828b35-6618-4d56-a37a-84ef03617d1e
  Devices successfully registered for library access

# 8. Verify devices are registered
$ sd library info
# You should see the remote device in the devices list
```

### Device B (iOS)

```bash
# 1. Enter pairing code from Device A in the app

# 2. After pairing completes, discover Device A's libraries
# (Use iOS UI or similar CLI commands when running on device)

# 3. Select libraries and set up sync
# (Use iOS UI for library selection)
```

## Output Formats

All commands support `--output` flag:

```bash
# Human-readable (default)
$ sd library sync-setup discover <DEVICE_ID>

# JSON output
$ sd library sync-setup discover <DEVICE_ID> --output json

# YAML output
$ sd library sync-setup discover <DEVICE_ID> --output yaml
```

## Common Use Cases

### Scenario 1: Simple Two-Device Setup

You have a desktop and a phone, both with "My Library" auto-created.

```bash
# On Desktop
sd pair generate
# Share code with phone

# After phone joins:
sd library sync-setup discover <PHONE_DEVICE_ID>
sd library sync-setup setup \
  --local-library <DESKTOP_LIBRARY_ID> \
  --remote-device <PHONE_DEVICE_ID> \
  --remote-library <PHONE_LIBRARY_ID>
```

### Scenario 2: Multiple Libraries

You want to choose which libraries to sync.

```bash
# Discover what libraries the remote device has
sd library sync-setup discover <REMOTE_DEVICE_ID>

# Set up sync for specific library pair
sd library sync-setup setup \
  --local-library <PHOTOS_LIBRARY_ID> \
  --remote-device <REMOTE_DEVICE_ID> \
  --remote-library <THEIR_PHOTOS_LIBRARY_ID>

# Optionally set up another pair
sd library sync-setup setup \
  --local-library <WORK_LIBRARY_ID> \
  --remote-device <REMOTE_DEVICE_ID> \
  --remote-library <THEIR_WORK_LIBRARY_ID>
```

### Scenario 3: One-Way Registration

Register your device in their library without syncing data.

```bash
sd library sync-setup setup \
  --local-library <MY_LIBRARY_ID> \
  --remote-device <THEIR_DEVICE_ID> \
  --action register-only
# No --remote-library specified
```

## Troubleshooting

### "Device not paired"

```bash
Error: Device must be paired before setting up library sync

Solution:
1. Check pairing status: sd pair status
2. Pair devices if needed: sd pair generate / sd pair join
3. Retry sync setup after pairing completes
```

### "Device offline"

```bash
Device: Bob's MacBook (550e8400-e29b-41d4-a716-446655440000)
Online: false

No libraries found on remote device

Solution:
1. Ensure remote device daemon is running
2. Check network connectivity
3. Verify devices can discover each other (mDNS)
4. Retry when device comes online
```

### "Library not found"

```bash
Error: Library not found: <UUID>

Solution:
1. List local libraries: sd library list
2. Verify library ID is correct
3. Create library if needed: sd library create <NAME>
```

### "Context not available"

```bash
Error: Context not available for library operations

Solution:
1. Restart the daemon: sd restart
2. Wait for initialization to complete
3. Check logs for networking initialization errors
```

## Integration with Other Commands

### List Paired Devices

```bash
# See all paired devices with details
$ sd network devices

Paired Devices (2 total, 1 connected):
  Name: Bob's MacBook
  ID: 550e8400-e29b-41d4-a716-446655440000
  Status: Connected

# See only connected devices
$ sd network devices --connected

# Check network status summary
$ sd network status
Networking: running
Paired: 2 | Connected: 1
```

### Verify Registration

After setup, the remote device should appear in your library's device list:

```bash
# Get library info (when UI supports it)
$ sd library info
# Device list will include the remote device
```

## Advanced Usage

### Custom Device ID

If you need to override the auto-detected local device ID:

```bash
sd library sync-setup setup \
  --local-library <LIBRARY_ID> \
  --remote-device <REMOTE_DEVICE_ID> \
  --local-device <CUSTOM_LOCAL_DEVICE_ID> \
  --leader local
```

### Specify Remote as Leader

If the remote device should be the sync leader:

```bash
sd library sync-setup setup \
  --local-library <LIBRARY_ID> \
  --remote-device <REMOTE_DEVICE_ID> \
  --remote-library <REMOTE_LIBRARY_ID> \
  --leader remote
```

## Future Commands (Phase 3)

When full sync is implemented, additional actions will be available:

```bash
# Merge remote library into local
sd library sync-setup setup \
  --local-library <LOCAL_ID> \
  --remote-device <DEVICE_ID> \
  --remote-library <REMOTE_ID> \
  --action merge-into-local \
  --leader local

# Merge local library into remote
sd library sync-setup setup \
  --local-library <LOCAL_ID> \
  --remote-device <DEVICE_ID> \
  --remote-library <REMOTE_ID> \
  --action merge-into-remote \
  --leader remote

# Create new shared library
sd library sync-setup setup \
  --remote-device <DEVICE_ID> \
  --action create-shared \
  --leader local
```

## See Also

- **Pairing**: `sd network pair --help`
- **Devices**: `sd network devices --help`
- **Libraries**: `sd library --help`
- **Networking**: `sd network --help`
- **Design**: `docs/core/LIBRARY_SYNC_SETUP.md`

## Quick Command Reference

```bash
# Pairing
sd network pair generate          # Generate pairing code
sd network pair join <CODE>       # Join with code
sd network pair status            # Show pairing sessions

# Devices
sd network devices                # List all paired devices
sd network devices --connected    # List connected devices only

# Library Sync Setup
sd library sync-setup discover <DEVICE_ID>
sd library sync-setup setup --local-library <ID> --remote-device <ID> [OPTIONS]

# Libraries
sd library list                   # List local libraries
sd library info                   # Show library details
```