Desktop client

What it does

The driftless command-line client keeps one local folder in sync with your account on the server. It runs on macOS, Windows, and Linux. Today it does full folder sync — the selected folder is downloaded completely; on-demand placeholder files are a later feature.

Install

The client is currently built from source. With Go 1.26 or newer:

go build -o driftless ./cmd/driftless

Move the resulting binary somewhere on your PATH. Pre-built downloads will come later.

Log in

Authenticate against your server. The password is read from standard input, so it is not stored in your shell history:

driftless login -server http://your-server:8080 -user alice

This saves the server address, a bearer token, and a generated device id in a small config file.

Where settings live

The client keeps a config.json (server, token, device, folder) and a state.json (what it has synced) in your operating system's config directory under driftless:

• macOS: ~/Library/Application Support/driftless
• Linux: ~/.config/driftless
• Windows: %AppData%\driftless

Pass -config DIR to any command to use a different directory — useful for syncing more than one folder or simulating a second device on the same machine.

Sync once

Reconcile a folder with the server a single time. The folder is remembered after the first run, so later you can just run driftless sync:

driftless sync -dir /path/to/folder

A sync pushes your local changes and then pulls anything newer from the server, including deletions.

Sync continuously

Leave the watcher running to keep the folder synced without thinking about it. It reacts to local changes (after a short quiet period so a burst of edits is sent together), and it subscribes to the server's change stream so edits made on your other devices arrive within a second — no waiting for a poll:

driftless watch
driftless watch -poll 30s -debounce 800ms

• -debounce — how long to wait after the last local change before syncing. Default 800ms.
• -poll — a fallback interval to re-check the server, in case the change stream drops a notification. Remote changes normally arrive instantly through the stream, so this rarely fires. Default 30s.

After a local change the watcher examines only the files and folders that changed, and it re-checks the whole folder when it starts and once an hour after that, in case a change slipped past it. The change stream reconnects on its own if the server restarts or the network blips. Press Ctrl-C to stop; the watcher shuts down cleanly.

Menu-bar app

If you would rather not keep a terminal open, the driftless-tray menu-bar app runs the same continuous sync with a small status menu. Build it the same way:

go build -o driftless-tray ./cmd/driftless-tray

On macOS you do not need the command line at all: launch the app and, if it is not configured yet, it walks you through setup with native dialogs — your server URL, sign-in, and the folder to sync — then starts syncing. You can change the server, account, or folder later from Preferences… in the menu. (On other platforms, configure it once with the CLI first: driftless login, then a single driftless watch -dir /path/to/folder to remember the folder.)

Its menu shows whether you are up to date, syncing, paused, or in error, and lets you pause and resume syncing or open the synced folder. The menu-bar icon is the Driftless mark, and it animates while a sync is in progress. Pass -config DIR to use a non-default config.

Because it draws a native menu-bar item, this binary is built with CGO (on by default in a normal Go toolchain), unlike the otherwise CGO-free client and server.

macOS app (early)

A native macOS app is taking shape alongside the CLI: it puts a Driftless location in Finder where your server files appear as placeholders — they take no disk space until you open them, and you can pin anything with Keep on this Mac from Finder's context menu. It is a menu-bar app that needs macOS 14 or newer. For now it is built from source in the repository's macos/ folder (see the README there), which can also produce a signed, notarized disk image; published downloads are not available yet. To install from a disk image, open it and drag Driftless into Applications — the app must run from there. The first time, enable the extension when the app asks (System Settings ▸ General ▸ Login Items & Extensions).

The app syncs while it is running; turn on Start Driftless at login in Settings ▸ General to keep it that way. Updates are manual for now: install a newer disk image over the old app.

Sync folders from this Mac

The app can also sync folders that already live on your Mac — nothing has to move into the Driftless drive. In Settings ▸ Sync Folders, click Add Folder… and pick any folder: your Documents, a projects directory, a folder on an external drive. Each added folder:

• stays exactly where it is and syncs both ways with your server, under a top-level folder named after it — ~/Projects becomes Projects on the server;
• shows up in the Driftless drive on your other devices; on this Mac the drive shows a small link under the folder's name that jumps to the real folder (the files live at their real path here, so you never get two copies);
• merges with a same-named folder added on another Mac — that is how you sync a folder between two Macs. Folder names are case-sensitive;
• keeps both copies on a conflict, as *.sync-conflict-* files — a simultaneous edit never silently wins.

Removing a folder from the list stops syncing but deletes nothing: the files stay in the folder and on your server, and the folder reappears in the Driftless drive in Finder. The first time you add a folder from Documents, Desktop, Downloads, or an external drive, macOS asks for permission once; if you decline, the folder's row shows the error and you can grant access later under System Settings ▸ Privacy & Security ▸ Files & Folders.

Folders of any size work. The app follows changes through macOS's file-system event stream, not one open handle per file, and after an edit it looks only at what changed — so a change in a folder of millions of files syncs as quickly as one in a small folder. Changes from your other devices are applied without re-reading the folder at all. When syncing starts, and once an hour after that, the app checks the whole folder in case anything slipped past the event stream; with millions of files that check runs for a while in the background. Uploads run in parallel — several files at once, and several pieces of each file — and the app records its progress every minute, so the first upload of a big folder picks up where it left off if the app quits or the Mac restarts. Memory use grows with the number of files a folder holds, at roughly 150 MB per million. If the app ever reports that it cannot reach its helper, the helper's log is at ~/Library/Logs/Driftless/helper.log.

Review conflicts

When simultaneous edits leave *.sync-conflict-* copies behind, the app gathers them under Settings ▸ Conflicts and turns each into one question: which version do you want to keep? The current file and each copy are listed side by side with device, date, and size; Show in Finder lets you Quick Look every version first, and choosing Keep This Version always confirms with the exact outcome spelled out — which file keeps what, which copies disappear, and that removed content stays in the server's history. Keeping a copy of a file that was deleted elsewhere restores it. The menu-bar popover nudges you when versions are waiting. See Conflicts and versioning for the rules that create these copies.

Sign out or uninstall

Settings ▸ Account ▸ Sign Out… removes the Driftless location from Finder, gives this Mac's token back to the server so it stops working immediately, and stops Sync Folders. Downloaded drive copies on this Mac are dropped; everything stays on your server, and your local Sync Folders stay where they are. (If the app took over a sign-in from the driftless command line, the token is left valid, because the command-line client still uses it.)

Settings ▸ General ▸ Uninstall Driftless… does everything sign-out does, then also removes the login item, the app's private data and preferences, and moves the app to the Trash. The confirmation spells this out before anything happens. Your Sync Folders and the command-line client's own settings are not touched, and nothing on the server is deleted.

Check status

See which server and folder a config is bound to and how many files it is tracking:

driftless status

Log out

To stop this device from syncing, sign it out:

driftless logout

This revokes the device's token on the server and removes it from the local config. Your other devices are unaffected, and neither the local folder nor anything on the server is deleted — driftless login puts the device back to work. If the server cannot be reached, the token is dropped locally anyway and the command says so, so signing out never silently fails. An admin can do the same from the server side for every device at once; see Security and remote access.

Sessions also lapse on their own: a device that has not synced for 180 days has to log in again. The limit measures idleness, so a device in daily use never asks for a password twice, and the server operator can change or disable it.