Cloud Sync

Optional cloud synchronization for backup and multi-device access.

Local-First Architecture

HZL uses a local-first design:

All reads and writes go to local SQLite
Fast, works offline
Cloud sync happens in the background

flowchart TD
    CLI[User / Agent CLI]
    subgraph Local["Local Machine"]
        Cache[(cache.db<br/>Reads)]
        Events[(events.db<br/>Writes)]
        Sync[Sync Engine]
    end
    Cloud[(Turso / Cloud)]

    CLI -->|Read| Cache
    CLI -->|Write| Events
    Events -->|Rebuild| Cache
    Events <-->|Sync| Sync
    Sync <-->|Replication| Cloud

Why Cloud Sync?

Backup - Data survives machine failures
Multi-device - Access tasks from different machines
Multi-agent - Agents on different machines share state
Collaboration - Teams can share a task database

Setting Up Cloud Sync

HZL integrates with Turso (libSQL).

1. Create a Turso Database

# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# Login
turso auth login

# Create database
turso db create hzl-tasks

# Get connection info
turso db show hzl-tasks --url
turso db tokens create hzl-tasks

2. Initialize HZL with Sync

hzl init --sync-url libsql://<db>.turso.io --auth-token <token>

Or add sync to existing installation:

hzl init --sync-url libsql://<db>.turso.io --auth-token <token>

3. Verify Sync

hzl status

Shows sync configuration and status.

How Sync Works

Writes

Event appended to local events.db
Projections rebuilt in local cache.db
Sync engine pushes to cloud (background)

Reads

Always from local database. No network latency.

Conflicts

HZL’s event-sourced design minimizes conflicts:

Events are append-only
Atomic claiming prevents duplicate claims
Sync merges events by timestamp

Manual Sync

Force a sync:

hzl sync

Useful after reconnecting to network.

Multi-Device Setup

Same database, different machines:

# Machine 1: Initialize with sync
hzl init --sync-url libsql://<db>.turso.io --auth-token <token>

# Machine 2: Initialize with same sync URL
hzl init --sync-url libsql://<db>.turso.io --auth-token <token>

Both machines now share the same task database.

Offline Behavior

When offline:

All operations work normally (local database)
Changes queue for sync
No errors or blocking

When reconnected:

Queued changes sync automatically
Or run hzl sync to force

Security Considerations

Auth token - Keep it secret, don’t commit to repos
Database access - Anyone with the token has full access
Network - Data encrypted in transit (TLS)

Store credentials securely:

# Environment variable
export HZL_SYNC_TOKEN=<token>

# Or in config file (~/.config/hzl/config.json)

Disabling Sync

To use local-only:

hzl init --reset-config

This resets to default local database without sync.

Troubleshooting

Sync Not Working

# Check status
hzl status

# Force sync
hzl sync

# Check for errors in output

Stale Data

If data seems stale:

hzl sync
hzl task list  # Should show updated data

Connection Issues

Verify sync URL is correct
Verify auth token is valid
Check network connectivity
Try hzl sync for detailed error messages