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.

Check status

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

driftless status