Obsidian Headless

Headless client for Obsidian Sync. Sync your vaults from the command line without the desktop app.

Requires Node.js 22 or later.

Install

npm install -g obsidian-headless

Authentication

Login interactively:

ob login

If already logged in, ob login displays your account info. To switch accounts, pass --email and/or --password to log in again.

Quick start

# Login
ob login

# List your remote vaults
ob sync-list-remote

# Setup a vault for syncing
cd ~/vaults/my-vault
ob sync-setup --vault "My Vault"

# Run a one-time sync
ob sync

# Run continuous sync (watches for changes)
ob sync --continuous

Commands

ob login

Login to your Obsidian account, or display login status if already logged in.

ob login [--email <email>] [--password <password>] [--mfa <code>]

All options are interactive when omitted — email and password are prompted, and 2FA is requested automatically if enabled on the account.

ob logout

Logout and clear stored credentials.

ob sync-list-remote

List all remote vaults available to your account, including shared vaults.

ob sync-list-local

List locally configured vaults and their paths.

ob sync-create-remote

Create a new remote vault.

ob sync-create-remote --name "Vault Name" [--encryption <standard|e2ee>] [--password <password>] [--region <region>]

| Option | Description | |---|----------------------------------------------------------| | --name | Vault name (required) | | --encryption | standard for managed encryption, e2ee for end-to-end | | --password | End-to-end encryption password (prompted if omitted) | | --region | Server region (automatic if omitted) |

ob sync-setup

Set up sync between a local vault and a remote vault.

ob sync-setup --vault <id-or-name> [--path <local-path>] [--password <password>] [--device-name <name>] [--config-dir <name>]

| Option | Description | |---|-----------------------------------------------------------------| | --vault | Remote vault ID or name (required) | | --path | Local directory (default: current directory) | | --password | E2E encryption password (prompted if omitted) | | --device-name | Device name to identify this client in the sync version history | | --config-dir | Config directory name (default: .obsidian) |

ob sync

Run sync for a configured vault.

ob sync [--path <local-path>] [--continuous]

| Option | Description | |---|---| | --path | Local vault path (default: current directory) | | --continuous | Run continuously, watching for changes |

ob sync-config

View or change sync settings for a vault.

ob sync-config [--path <local-path>] [options]

Run with no options to display the current configuration.

| Option | Description | |---|---| | --path | Local vault path (default: current directory) | | --mode | Sync mode: bidirectional (default), pull-only (only download, ignore local changes), or mirror-remote (only download, revert local changes) | | --conflict-strategy | merge or conflict | | --file-types | Attachment types to sync: image, audio, video, pdf, unsupported (comma-separated, empty to clear) | | --configs | Config categories to sync: app, appearance, appearance-data, hotkey, core-plugin, core-plugin-data, community-plugin, community-plugin-data (comma-separated, empty to disable config syncing) | | --excluded-folders | Folders to exclude (comma-separated, empty to clear) | | --device-name | Device name to identify this client in the sync version history | | --config-dir | Config directory name (default: .obsidian) |

ob sync-status

Show sync status and configuration for a vault.

ob sync-status [--path <local-path>]

ob sync-unlink

Disconnect a vault from sync and remove stored credentials.

ob sync-unlink [--path <local-path>]

Native modules

btime

The btime directory contains a prebuilt native N-API addon for setting file creation time (birthtime) on Windows and macOS. This is used when downloading files from the server to preserve their original creation timestamps.

Since it targets N-API version 3, the compiled .node binaries are ABI-stable and work across Node.js versions without recompilation.

On Linux, birthtime is not supported — the addon is not included and sync operates normally without it.

Prebuilt binaries are included for:

• win32-x64
• win32-arm64
• win32-ia32
• darwin-x64
• darwin-arm64