Install and authenticate Headless

Open beta Node.js 22+

Obsidian Headless is the standalone ob client for Sync and Publish. It does not require desktop Obsidian.

1. Confirm the runtime

Use a dedicated Node.js 22 or later runtime:

node --version
npm --version

The VitePress documentation project uses Node 20.x for builds. That build runtime is separate and does not satisfy the Headless requirement.

2. Install

npm install -g obsidian-headless

Verify that the global npm binary directory is on PATH and that the client resolves:

command -v ob
ob --help

On Windows, use where ob in Command Prompt if command -v is unavailable. Restart the terminal after changing PATH.

3. Entitlement checkpoint

Headless Sync and Publish require active paid subscriptions. Before account use, an authorized owner must identify the approved account alias and read back the required entitlement without exposing credentials. Documentation of a capability is not authorization to buy, enable, renew, upgrade, or change billing.

4. Interactive authentication only

Authentication is a hard gate. After exact approval names the account alias and action, the owner or approved managed test-account operator runs:

ob login

Omit every credential-bearing option so email, password, and MFA are prompted interactively. If already authenticated, ob login displays account information; do not use it to switch identity without separate approval.

The official surface includes credential option names, but this program treats them as non-runnable metadata only. Never place their values in commands, files, logs, CI, chat, prompts, screenshots, or receipts.

ob logout clears stored credentials. It is an account-state mutation and requires exact approval plus a rollback owner.

5. Stop conditions

Stop if:

• Node is older than 22;
• ob does not resolve after PATH verification;
• the approved account alias or entitlement is unknown;
• the prompt requests credentials but the approved owner/operator is absent;
• login would switch account identity;
• a paid-service or billing change is required.

Do not improvise with credential flags or secret injection.

Source

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