ContextQMD
Back to Spacedrive

CLI: Library Sync Setup Commands

docs/cli/library-sync-setup.mdx

0.4.312.2 KB
Original Source

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