CLI
Quick start
flockfs login # sign in in the browser and choose your drive
flockfs mount # the drive appears at ~/flockfs (macOS: runs in the background)
flockfs unmount ~/flockfs
flockfs setup # or: a real local copy at ~/flockfs, always in sync (macOS: starts at login)flockfs login keeps the sign-in (macOS Keychain; elsewhere a 0600 file in ~/.flockfs) and
refreshes it automatically, so commands without --url / --token use it: flockfs ls,
flockfs get notes.md, flockfs mcp, flockfs sync DIR, flockfs setup, flockfs run.
Background sync started by flockfs setup or flockfs sync DIR --install gets no token: it opens
the same sign-in itself, also after a restart or a reboot (the LaunchAgent holds only the server
and the drive id).
Options and commands
Global options: --url (FLOCKFS_URL; default: the server of flockfs login, else a local
development server at http://127.0.0.1:4317), --token (FLOCKFS_TOKEN),
--token-file (FLOCKFS_TOKEN_FILE, default data/token), --actor (label for your edits when the server does
not derive one from the token), --drive (FLOCKFS_DRIVE; see Drives).
A token given by flag or environment (--token, FLOCKFS_TOKEN, --token-file,
FLOCKFS_TOKEN_FILE) always wins over the sign-in, and --url pointing at a server you are not
signed in to works exactly as without flockfs login.
| Command | What it does |
|---|---|
flockfs login [--url URL] [--no-browser] | Sign in in the browser (default https://app.flockfs.com): the consent page picks the drive (or several drives at once: each is saved as its own sign-in) and access. Saved for later commands and refreshed automatically; signing in to another drive adds it (--drive picks it, the latest is the default). --no-browser prints the link. |
flockfs login --status, flockfs whoami | The saved sign-ins (server, drive, whether they work, where the credentials are). |
flockfs logout [--url URL] | Sign out: revoke each saved connection on its server, then forget the sign-ins on this computer (only that server's with --url). If the server can't be reached the local sign-in is still removed, and the connection stays in Access until it expires (30 days unused) or is revoked there. |
flockfs setup [DIR] [--check | --stop] [--open] [--no-autostart] | Connect DIR (default ~/flockfs, or ~/flockfs-<slug> with --drive for a drive other than the default), start always-on sync, verify both directions; prints JSON. Uses the flockfs login sign-in when no token is given. |
flockfs sync DIR [--once] | Keep a folder in sync (filesystem events + live change feed). --once = one pass. |
flockfs sync DIR --install [--no-load] / --uninstall | macOS LaunchAgent: start at login, restart on crash. After flockfs login it holds no token: the daemon opens the sign-in itself. |
flockfs status DIR [--json] | Drive, daemon, connection, last sync, tracked files, conflicts, autostart. |
flockfs resolve DIR PATH --take local|remote | Settle a preserved conflict. |
flockfs mcp | MCP server on stdio (actor mcp-agent unless --actor; --drive picks the drive). |
flockfs drives list [--json] [--deleted] | Drives you can open (* = the server's default). |
flockfs drives create NAME [--slug S], rename DRIVE [--name N] [--slug S] | New drive (team owners); rename (old slugs keep working). |
flockfs drives delete DRIVE [--yes], restore DRIVE [--slug S] | Soft delete (purged after 30 days; asks you to type the slug unless --yes); undo. |
flockfs fork [DRIVE] [--name N] [--snapshot] | Duplicate a drive (default --drive): a new drive that starts as an exact copy; large files are shared, so it takes seconds. --snapshot: read-only. Owners only. |
flockfs copy-to DRIVE PATH... [--folder F] [--replace] | Copy files or folders from this drive (--drive) into another drive. Same-named files are kept side by side (a (copy).md) unless --replace. |
flockfs export [-o FILE.zip | --dir DIR] [--history] | The drive as a zip (files + .flockfs/manifest.json; default <slug>.zip, -o - for stdout), or unpacked as ordinary files into a new folder; --history adds every version under .flockfs/history/. |
flockfs ls [PREFIX], get PATH [-o FILE], put PATH [-i FILE] [--revision N] | List, read, write (stdin/stdout by default). |
flockfs get --text PATH [-o FILE] | The extracted text of a PDF, DOCX, XLSX or PPTX file (Markdown: headings, paragraphs, tables), instead of its bytes. See Documents. |
flockfs mkdir, append PATH TEXT, mv SRC DST, rm PATH | Folders, atomic append, move/rename, delete. |
flockfs pipe PATH [-q] | Append standard input to a file as it arrives, like tee into the drive: npm run build 2>&1 | flockfs pipe logs/build.log. See Pipe. |
flockfs copy, flockfs paste [--os] | A clipboard shared by your computers and agents: clipboard.txt in your personal drive (--drive for a team clipboard). See Clipboard. |
flockfs search QUERY [--names|--content] [--limit N], links PATH | Names (first) and contents (text files and the extracted text of documents); outgoing links and backlinks. |
flockfs history PATH, restore PATH REVISION | Versions; restore one as a new revision. |
flockfs restore --to TIME [--path FOLDER] | Put the drive (or a folder) back to how it was at a time within the history window. |
flockfs sessions [--agent NAME] [--limit N] [--json] | Recent sessions (who did what, when): the units flockfs undo works on. |
flockfs undo --session S [--dry-run] [--json] | Undo everything one session changed, keeping later edits by others. |
flockfs watch [--after N] [--prefix FOLDER] | Stream change events as JSON lines; --prefix keeps one folder or file (moves in/out included). |
flockfs timeline [--agent NAME|ID] [--path P] [--session S] [--since 1h] [--json] [--follow] | What agents did: MCP tool calls and logged actions (time, actor, tool, path, ok/error, duration). See Timeline. |
flockfs timeline --export FILE [--format jsonl|csv] [filters…] | Save the whole matching timeline to a file (-: standard output). Team plan, drive owners. |
flockfs mount [DRIVE] [DIR] [--foreground] [--read-only] [--port N] [--no-mount], flockfs unmount DIR | A drive as a live folder with no local copy: files stream from the server (user-space NFS on 127.0.0.1). Default folder ~/flockfs (other drives ~/flockfs-<slug>); on macOS it runs in the background and returns once mounted (--foreground to stay attached). See Mount. |
flockfs mounts, flockfs mount --status | Active mounts: folder, drive, server, pid, state. |
flockfs run [--path FOLDER] [--read-only] [--agent-token-name NAME [--scope FOLDER]] [--sync | --mount] [--dir DIR] [--keep] [-q] -- COMMAND… | Run any program or agent in a live drive: mounted into a temporary folder, writes saved and folder removed when it exits; its exit code is returned. See Run. |
Drives
A server holds one or more drives (separate trees with their own members, tokens and history; see API.md). Every command works on one drive, chosen by:
--drive DRIVE(id, slug orslug-id), elseFLOCKFS_DRIVE, else- the folder's own drive for
sync,statusandresolve(stored as the drive's permanent id inDIR/.flockfs/state.json), else - the drive of an agent token (
flockfs_<driveid>_…), else - the server's default drive.
A synced folder belongs to exactly one drive: naming another one fails with "folder belongs to
drive X" (folders synced before the server had drives belong to its default drive). Renaming a
drive is safe: folders and LaunchAgents (--drive <id>) refer to it by id. Give each drive its
own folder (flockfs setup --drive research uses ~/flockfs-research, next to ~/flockfs).
flockfs drives create Research # research k3vzq2m7xa4b owner Research
flockfs --drive research put notes/a.md -i a.md
flockfs setup --drive research # ~/flockfs-research, always in sync
flockfs mount research /tmp/research # or: flockfs --drive research mount /tmp/research
flockfs --drive research export --dir ./research-backup
flockfs fork research --name "Research try" # research-try … owner Research try
flockfs --drive research-try copy-to research notes/a.md --replace # copy one file backSync
The folder is plain files. A local save is sent about 60 ms after the last filesystem event
(at most 400 ms during a burst of events; deletions wait 1 s, so editors that save by renaming
are not mistaken for deletes). Only the
changed paths are re-examined, with a full rescan every 30 s as a safety net); remote edits
arrive over a long-poll feed (a request held up to 55 s, at most one a second). New content of
a text file costs one fetch of that file; the drive is listed again only for creates, moves,
deletes, access changes, reconnects and every 5 minutes as a backstop. An idle daemon makes
about 90 requests an hour, one following someone typing about two a second. Saves are sent with the revision they were based on, so
concurrent text edits merge; overlapping edits, or concurrent edits of a binary file, are
conflicts: your version stays in place, the other one is saved as
DIR/.flockfs/conflicts/<id>/r<revision>.remote.<ext>, and the sync log and flockfs status
print both paths and the command to keep one (flockfs resolve DIR PATH --take local|remote).
While someone keeps editing a file elsewhere (typing in the browser), its new text is written
to disk at most once a second (the first change at once, the last within a second), so local
editors are not asked to reload after every keystroke. An editor that did not reload can still
save its older buffer: the daemon keeps the texts it replaced on disk for 10 minutes, and a save
that is closer to one of them than to the current text is merged onto the current text instead
of undoing the other edits ("saved from an older version; merged" in the log); if both changed
the same text it is a conflict as above. Once a save starts from the current text, the editor
counts as caught up, so undoing someone's change on purpose afterwards is sent as is. Renames and
folder moves keep file identity. version control stores (.git, .jj, ...), dependency caches (node_modules, .venv, ...), editor swap files and OS metadata never sync;
symlinks are neither synced nor followed. .flockfs/ holds the checkpoint, logs and
status.json (state: starting, saved, conflicted, locked (local changes waiting on someone's lock), offline, error, stopped).
Ctrl-C or SIGTERM (e.g. launchctl bootout) stops the daemon gracefully: a pass in progress
finishes and saves its checkpoint first.
Pipe
flockfs pipe PATH appends standard input to PATH (created with its folders if missing) and
copies it to standard output (-q/--quiet does not). Lines are sent in batches: one second
after the first unsent line, as soon as 64 KiB are waiting, and at the end of the input, so a
chatty command costs about one request a second. Each batch is an atomic append, so several
commands can pipe into one file while others watch it live. A text file holds at most 2 MiB:
when the next batch would not fit, the file is rotated like logrotate does (PATH.4 becomes
PATH.5, the old PATH.5 is deleted, …, PATH becomes PATH.1) and a fresh PATH continues;
renamed files keep their history. If the server cannot be reached, the text waits (up to 16 MiB)
and is retried; at the end of the input it gets five more tries before flockfs pipe fails.
Clipboard
flockfs copy and flockfs paste share a clipboard across your computers, terminals and agents.
It is the plain file clipboard.txt at the root of your personal drive (the default drive of
your sign-in), or of --drive DRIVE for a team clipboard. flockfs copy stores standard input
when something is piped in (cat notes.txt | flockfs copy), else this computer's clipboard.
flockfs paste prints it; in a terminal (or with --os) it also puts it on this computer's
clipboard, ready to paste anywhere. The OS clipboard is pbcopy/pbpaste on macOS and
wl-copy/wl-paste, xclip or xsel on Linux. Text only.
Mount
flockfs mount makes an empty folder a live window onto a drive with no local copy:
~/flockfs for the default drive, ~/flockfs-<slug> for another one (flockfs mount DRIVE), or
any empty folder (flockfs mount [DRIVE] DIR; one argument is a folder if it contains /, starts
with . or ~, or exists, else a drive). The folder is created if missing. No kernel
extension is needed: it runs an NFSv3 server on 127.0.0.1 and mounts it with the OS's own
NFS client (no sudo on macOS for a folder you own; Linux prints a sudo mount command). Changes
from elsewhere appear within milliseconds (driven by the change feed). Files are read when
opened (large files in 1 MiB blocks) and cached in memory only, within fixed limits. Writes are
sent ~300 ms after the last write to a file, and close/fsync return only once the server has
the file: appends via the atomic append API, everything else with its base
revision and base content so the server merges concurrent text edits (unmergeable versions are
kept as name (conflict …).ext). Atomic saves (write-temp + rename, vim/JetBrains backup
renames) keep the file's identity; .DS_Store, ._* and editor scratch files stay in memory.
Someone else's lock fails writes with "Permission denied" without losing the buffered data; a
read-only token mounts read-only. On macOS the mount runs detached and the command returns once
the folder is mounted (--foreground keeps it in the terminal; --background is accepted and
changes nothing); on Linux it runs in the foreground. flockfs mounts lists what is mounted.
Ctrl-C (foreground), SIGTERM or flockfs unmount DIR unmount cleanly after saving
pending writes. Mounting is the default; use flockfs sync for a full local copy. Details,
mount options and measurements: mount.md.
Run
flockfs run -- COMMAND gives any program or agent a live flockfs drive in one command:
flockfs run -- claude # a coding agent, working in the drive
flockfs run --drive research --path inbox -- python agent.py # start in research's inbox/
flockfs run --read-only -- grep -r TODO . # writes fail with "Read-only file system"
flockfs run --agent-token-name triage --scope inbox -- python agent.py # least privilege (owners)It mounts the drive into a new /tmp/flockfs-run-… folder (or --dir DIR), starts COMMAND there
(in --path FOLDER, created if missing) with stdio passed through, and when COMMAND exits saves
its pending writes, unmounts, removes the folder (--keep keeps it) and exits with COMMAND's
exit code (128 + N if signal N ended it). Ctrl-C and SIGTERM/SIGHUP go to COMMAND first; cleanup
always runs. Where mounting is not possible (Linux without root), it falls back to a temporary
folder kept live by the sync daemon (--sync forces this, --mount forbids the fallback).
COMMAND gets FLOCKFS_URL, FLOCKFS_DRIVE (the drive id), FLOCKFS_TOKEN_FILE (a 0600 file deleted
afterwards; the token is never on a command line, and FLOCKFS_TOKEN is removed; with the
flockfs login sign-in the file is replaced with each refreshed access token, so long runs keep
working, and long-running flockfs commands reading it follow it), FLOCKFS_WORKSPACE
(the folder) and FLOCKFS_SESSION (a UUID sent as X-Flockfs-Session by every flockfs client in the
run, so its changes can be grouped). flockfs commands inside the run pick all of these up.
--agent-token-name NAME (drive owners) runs COMMAND, and the drive itself, with a new
agent token labelled NAME (write, or read with --read-only; limited to --scope FOLDER,
default --path), valid one day and revoked when COMMAND exits: its changes are attributed to
NAME and it cannot touch anything outside the scope. Details: mount.md.
Limiting the agent to a folder is part of the Team plan. On Starter, --scope is refused with that
reason, and --path alone starts the agent in the folder with access to the whole drive.
Install the CLI
curl -fsSL https://flockfs.com/install | shThis installs flockfs into ~/.local/bin for macOS (11 or later, Apple silicon or Intel) or
Linux (x86_64 or aarch64, glibc 2.35 or later, e.g. Ubuntu 22.04+, Debian 12+, Fedora 36+).
The installer picks the build for your computer, checks it against the published SHA-256
checksums and prints the next steps. Options: sh -s -- --dir DIR installs elsewhere,
sh -s -- --system into /usr/local/bin (with sudo). Run it again to update. Check with
flockfs --version, then open a drive's Connect dialog in the web app for the commands
to mount or sync it. Windows is not supported yet; use WSL.
Manual download: each build is a .tar.gz holding the flockfs binary, its license and the
third-party notices, next to a SHA256SUMS file, at
https://dl.flockfs.com/cli/latest/flockfs-PLATFORM.tar.gz where PLATFORM is darwin-arm64,
darwin-x86_64, darwin-universal, linux-x86_64 or linux-aarch64 (a specific version:
cli/vX.Y.Z/ instead of cli/latest/). Check it with shasum -a 256 -c SHA256SUMS --ignore-missing (Linux: sha256sum -c SHA256SUMS --ignore-missing), unpack it and put
flockfs on your PATH.
Exclusive creation
flockfs put PATH --exclusive creates the file only if its path is absent. It
accepts stdin or --input FILE; concurrent creators have one winner, and existing
content is never replaced. This cannot be combined with --revision. See
Coordinating agents with plain files.