Documentation
Applies to client v3.x. The wire protocol is documented separately and stays
compatible across minor versions.
1 · Install the client
Desktop and mobile builds are on the downloads page. The CLI ships as a single static binary and is the fastest way to script a headless node:
$ curl -fsSL https://get.riverline.dev | sh $ riverline login
2 · Pair a device
A workspace key is generated the first time you sign in. Every further device is approved from an already-paired one — either by scanning the short code or by confirming the fingerprint shown on both screens.
$ riverline pair device fingerprint 7f3a 91c2 4e08 b5d6 approve from studio-mbp? (y/N) y ✓ paired — workspace key wrapped for this device
Unpairing wipes the wrapped key, not your files. The workspace key itself can be rotated, but that forces every device to re-pair and re-index.
3 · Choose what syncs
Nothing is uploaded until you point the client at a folder. Selective sync keeps a placeholder on small disks and pulls blocks on demand:
$ riverline add ~/Work/Design --selective $ riverline add ~/Work/Contracts $ riverline status Design 4,182 files 12.4 GB synced Contracts 318 files 186 MB syncing 92%
4 · Bandwidth and idle behaviour
Sync is bidirectional by design: the client keeps a fresh block index on the server, so a device that has been offline for a week uploads what it changed and downloads what others changed. Steady state is a slow trickle of index updates; bulk transfer only happens when files actually move.
$ riverline config set max-upload 20Mbps $ riverline config set max-download 50Mbps $ riverline config set sync-on-battery false
Defaults are unlimited on AC power and paused on battery for laptops. On a server, set both caps before the first large folder, otherwise the initial index can saturate a small uplink.
5 · Conflicts
Two devices editing the same file without an intermediate sync produce a conflict copy rather than a silent overwrite. The losing side is renamed with the device and timestamp, and the original stays untouched:
Contracts/2026-acme.pdf Contracts/2026-acme (conflict studio-mbp 2026-11-18 14:02).pdf
Conflicts are listed under riverline conflicts. Nothing is deleted automatically.
6 · What the server can see
- File sizes, block counts and modification times — needed to schedule transfers.
- Folder names, because paths are needed for selective sync. Names can be encrypted on Business.
- Not file contents, not the workspace key, not the passphrase.
Changelog
Stuck on something? Write to support — we answer within a day, usually within the hour.