Skip to main content
NoteCoveNoteCove

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 notecove CLI 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 --ssh targets 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.