Complete Headless Sync reference

Open beta Paid service and mutation gates

Headless Sync requires Node.js 22+, an active Obsidian Sync subscription, approved interactive authentication, and a recoverable backup. Never run desktop Sync and Headless Sync on the same device; use one Sync method per device. It uses the standalone ob command, not the desktop-app obsidian CLI.

Read-only inventory commands may be documented without authorizing account use. Creation, setup, configuration, continuous operation, destructive modes, and unlink require exact approval.

Evidence rule

ob sync-status reports local configuration/status but cannot prove cross-device convergence by itself. Require source and destination status, second-device exact path/content/SHA-256 readback, conflict/deletion checks, and a named rollback owner.

Commands

ob sync-list-remote

Read-only inventory of remote and shared vaults available to the authenticated account. Account authentication remains separately gated. No options.

ob sync-list-local

Read-only inventory of locally configured vaults and paths. No options.

ob sync-create-remote

Creates a remote vault. This is a paid account/service mutation. Stop for exact approval naming the account alias, vault name, encryption mode, region, cost, and rollback owner. Any encryption password is prompted interactively and never placed in a command.

Non-runnable option metadata:

Option	Required	Meaning
--name	yes	Remote vault name
--encryption	no	standard or e2ee
--password	no	E2EE password; prompt interactively when omitted
--region	no	Server region; automatic when omitted

ob sync-setup

Links a local path and remote vault. Back up the source and obtain exact approval before setup. Any encryption password is prompted interactively and never placed in a command.

Non-runnable option metadata:

Option	Required	Meaning
--vault	yes	Remote vault ID or name
--path	no	Local directory; current directory when omitted
--password	no	E2EE password; prompt interactively when omitted
--device-name	no	Device name shown in Sync version history
--config-dir	no	Config directory name; .obsidian by default

ob sync

Runs Sync for an already configured vault. A one-shot run may upload or download according to the approved mode. Continuous operation requires exact approval, supervision, bounded redacted logs, health checks, restart limits, and a stop/disable procedure.

Option	Meaning
--path	Local vault path; current directory when omitted
--continuous	Watch continuously for changes

ob sync-config

Run with no mutation options to read the current configuration. Any setting option mutates the mapping and requires a backup plus exact approval.

Option	Meaning and safety
--path	Local vault path
--mode	bidirectional, pull-only, or mirror-remote; pull-only ignores local edits and mirror-remote reverts local edits
--conflict-strategy	merge or conflict
--file-types	Comma-separated image, audio, video, pdf, unsupported; empty clears
--configs	Comma-separated app, appearance, appearance-data, hotkey, core-plugin, core-plugin-data, community-plugin, community-plugin-data; empty disables config Sync
--excluded-folders	Comma-separated exclusions; empty clears
--device-name	Client identity in Sync version history
--config-dir	Config directory name

mirror-remote is destructive to local edits. pull-only is not a safe writer mode. Both require explicit role, scope, evidence, backup, and rollback decisions.

ob sync-status

Read-only local status and configuration for a vault. Supports optional --path. It is not cross-device convergence proof.

ob sync-unlink

Disconnects a vault from Sync and removes stored credentials. Supports optional --path. Exact approval and a rollback plan are required.

Native-module note

The official page documents birthtime support on Windows and macOS. Linux does not include the birthtime addon; Sync otherwise operates normally. Compare exact paths, bytes/content, and hashes rather than treating creation-time differences alone as lost content.

Recovery

No official Headless history, exact-version read, or restore command is documented. Use a recoverable backup plus documented desktop Sync/File Recovery or a separately verified provider workflow. See Recovery.

Source

First-party source retrieved 2026-08-29 EDT: Headless Sync. See Sources.