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.

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 currently built from source in the repository's macos/ folder (see the README there); a signed, downloadable build is the next milestone.

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.

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.

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.