@withmarfa/sync

Headless engine that keeps one or more local folders two-way synced with a Marfa server. Watches the disk, listens to the server's SSE stream, reconciles both directions with conflict detection.

The engine is UI-agnostic — a CLI ships in this package and drives the engine over a loopback HTTP control surface; menu-bar and desktop UIs use the same surface.

Install

npm install -g @withmarfa/sync

Quick start

marfa-sync start <folder> --url <api-url> --key <api-key>

Subsequent roots can be added at runtime:

marfa-sync roots add <path>
marfa-sync status

--daemon writes a launchd plist (macOS) so the engine survives terminal sessions. Run marfa-sync --help for the full command list.

Mapping rules

<root>/.marfa/mappings.json (optional) decides what type each file becomes when synced. Resolution order, first match wins:

1. Frontmatter type: if present (text files only)
2. User rules from mappings.json
3. Built-in mime defaults (image/* → core.file.image, audio, video)
4. Fallback: core.file

Example — promote any .md file in Notes/ to core.note, populating title from the first H1, body from everything after the frontmatter, and tags from the frontmatter:

{
  "rules": [
    {
      "id": "notes",
      "match": { "glob": "Notes/**/*.md" },
      "transform": {
        "type": "core.note",
        "tier": "library",
        "propertyExtractors": [
          { "kind": "first-h1", "into": "title" },
          { "kind": "body-after-frontmatter", "into": "body" },
          { "kind": "frontmatter-key", "key": "tags", "into": "tags" }
        ]
      }
    }
  ]
}

Match predicates: glob, mime, frontmatter (key/value match, or true for presence). All present predicates AND together.

Configuration

The agent merges configuration from three sources (highest priority first):

1. CLI flags — --url, --key, --types
2. Environment variables — MARFA_API_URL, MARFA_API_KEY
3. Config file — ~/.marfa/sync.json

Requires @withmarfa/sdk@^5.7.0.

Upgrading

Notable releases ship migration notes in CHANGELOG.md. The most consequential ones to read before upgrading:

• 0.11.0 — drops the legacy sync-agent extension namespace. Run the server-side namespace migration before installing this version if your data carries extensions['sync-agent'].*. A direct 0.9.x → 0.11.0 jump without the migration silently loses extension data. Newer Marfa servers emit a boot-time WARN when un-migrated rows are detected.
• 0.9.0 — package renamed from @withmarfa/sync-agent to @withmarfa/sync. Rename your package.json dependency.

More

Full per-root layout, mapping internals, the loopback HTTP control surface, and conflict-resolution semantics live in the repository.