Sync Storage Directories via SSH or Locally
notecove link keeps a storage directory (SD) in sync with one or more copies — on remote hosts
over SSH, or in another location on the same machine — bidirectionally, automatically, and
indefinitely. It’s a standalone CLI process: nothing else needs to be running on either side.
No app required on either end
This is the key difference from notecove serve and the
headless daemon: notecove link doesn’t project one
machine’s desktop app to another, and it doesn’t need a daemon installed on the remote. Each side
just needs the notecove CLI and a copy of the SD’s files on disk. notecove link runs on one
side (wherever you start it) and drives the sync directly over SSH (or, for --local, straight
over the filesystem) — no persistent remote process, no app, no daemon.
A desktop app or headless daemon pointed at the same SD can optionally be configured to launch and
manage a notecove link process for convenience, but that’s purely optional — notecove link
works the same with or without one.
What gets synced
Everything in the storage directory: notes, tasks, and their CRDT activity logs, plus media and attachment files — not just the logs that reference them. A note with an embedded image or a task with a file attachment replicates in full on both sides.
Prerequisites
- The
notecoveCLI installed on both sides. If the remote doesn’t have it yet:notecove install-cli --ssh user@remotehost - SSH access to the remote (key-based auth recommended) — for
--sshtargets only - A copy of the same storage directory present at a path on each side (same
sd-id)
Sync over SSH
notecove link \
--root /path/to/local/sd --sd-id <sd-id> \
--ssh user@remotehost --remote-root /path/to/remote/sd
This starts a long-running process: it connects to the remote over SSH, runs notecove sync-agent
there, and keeps both sides converged until you stop it (Ctrl+C).
Multiple remotes
Repeat --ssh/--remote-root (in matching order) to sync the same SD with several remotes at
once, each over its own independent connection:
notecove link --root /path/to/sd --sd-id <sd-id> \
--ssh user@vm1 --remote-root /sd/on/vm1 \
--ssh user@mac-mini --remote-root /sd/on/mac-mini
Sync locally (no network)
--local <path> syncs with a second copy of the same SD elsewhere on disk — an external drive, a
mounted volume, a second profile directory — with no network or SSH involved at all:
notecove link --root /path/to/sd --sd-id <sd-id> --local /Volumes/Backup/sd-copy
--local is repeatable and can be combined with --ssh in the same command to fan out to both
local and remote copies at once.
Multiple storage directories at once
For syncing several SDs at once, each with its own independent set of destinations, point
--config at a JSON config file instead of passing --root/--sd-id/--ssh/--local directly:
notecove link --config link-config.json
--config is mutually exclusive with --root/--sd-id/--ssh/--local — a config file always
replaces those flags entirely, never supplements them. --status, --ssh-command, --ssh-opts,
and --remote-notecove-command still apply (they’re process-wide, not per-SD).
Config file format
{
"sds": [
{
"sdId": "sd-main",
"root": "/path/to/local/sd-main",
"destinations": [{ "type": "local", "path": "/Volumes/icloud/sd-main-copy" }]
},
{
"sdId": "sd-backup",
"root": "/path/to/local/sd-backup",
"dbPath": "/custom/path/sd-backup.sqlite",
"secretEnvVar": "BACKUP_SD_PASSPHRASE",
"destinations": [
{ "type": "ssh", "host": "backup-host", "remoteRoot": "/remote/backup" },
{ "type": "local", "path": "/copies/backup-2" }
]
}
]
}
The top-level object has one key, sds: a non-empty array, one entry per storage directory. Each
entry is independent — its own root, its own identity/watermark db, its own secret, and its own
destination set — so one SD’s config, or one of its destinations, can fail or be fixed without
touching the others.
SD entry fields:
| Field | Required | Description |
|---|---|---|
sdId |
yes | This SD’s id. Must be unique across the whole config file. |
root |
yes | Path to this SD’s local copy. |
dbPath |
no | Local sqlite file for this entry’s watermark/identity state (default: ~/.notecove/link/<sd-id>.sqlite). |
secretEnvVar |
no | Name of an environment variable holding the SD’s passphrase, for an encrypted SD. See below — never a literal secret. |
destinations |
yes | Non-empty array of destination objects (see below). |
Destination fields — each entry’s type is either "ssh" or "local":
Field (type: "ssh") |
Required | Description |
|---|---|---|
host |
yes | SSH destination, e.g. user@remotehost — same as the CLI’s --ssh. |
remoteRoot |
yes | Path to the SD on the remote host — same as --remote-root. |
remoteSdId |
no | The SD id on the remote, if different from this entry’s sdId. |
remoteDbPath |
no | The remote sync-agent’s --db-path, if its default location isn’t writable there. |
Field (type: "local") |
Required | Description |
|---|---|---|
path |
yes | Path to a second local copy of the same SD — same as the CLI’s --local. |
dbPath |
no | This local target’s own identity/watermark sqlite file (default: ~/.notecove/link/<sd-id>-local-<hash>.sqlite). |
An entry can mix "ssh" and "local" destinations freely, and have as many of each as needed.
Secrets: secretEnvVar, never an inline value
A config file can never contain a literal passphrase, recovery key, or other secret — secret,
passphrase, and recoveryKey keys are rejected outright on an SD entry. For an encrypted SD,
name an environment variable instead via secretEnvVar; notecove link --config reads the actual
passphrase from that variable at startup, for that entry only:
BACKUP_SD_PASSPHRASE='...' notecove link --config link-config.json
This is what lets one --config process unlock several differently-encrypted SDs at once, each
supplying its own secret through its own named variable.
Checking status for every SD in a config
notecove link --config link-config.json --status
Prints { "sds": [...] } — one status report per entry, in config-file order — and exits
immediately without starting any session, same as single-SD --status.
Checking status
notecove link --root /path/to/sd --sd-id <sd-id> --status
Prints the SD’s key state and per-destination watermarks as JSON and exits immediately — it never
starts a session or connects to anything, so it’s safe to run alongside an already-running link
process.
How changes propagate
notecove link reacts to local file-system changes near-instantly: it watches the SD’s activity
log and pushes as soon as it sees a change (debounced by 300 ms to coalesce bursts of writes). A
30-second poll acts purely as a backstop in case a change is missed. On connection loss, it retries
with exponential backoff (5 s, 10 s, 20 s, 40 s, up to 60 s between attempts) and detects dead
connections via heartbeat (every 10 s, declared dead after 30 s with no response). When a
connection recovers, only the changes since the last sync are exchanged — no full resync.
You don’t need to restart notecove link after a network blip, SSH timeout, or sleep/wake —
leave it running (e.g. in tmux) and it reconnects on its own.
Related documentation
- Access NoteCove Remotely —
notecove serve’s SSH-forwarded tunnel, an alternative for occasional CLI access - Set Up a Headless Remote Daemon — an optional daemon that can manage a
notecove linkprocess for you - Remote CLI Access — overview of all the remote-access options