Obsidian Headless

Obsidian Headless (open beta) is a headless client for Obsidian services. It lets you sync vaults from the command line without the desktop app, with all the speed, privacy, and end-to-end encryption benefits of Obsidian Sync.

Reasons you might use Obsidian Headless:

  • Automate remote backups.
  • Automate publishing a website.
  • Give agentic tools access to a vault without access to your full computer.
  • Sync a shared team vault to a server that feeds other tools.
  • Run scheduled automations e.g. aggregate daily notes into weekly summaries, auto-tag, etc.
Obsidian Headless vs Obsidian CLI

Obsidian CLI controls the Obsidian desktop app from your terminal. Obsidian Headless is a standalone client that runs independently, no desktop app required.

Install

Obsidian Headless (open beta) requires Node.js 22 or later. Install it from npm:

npm install -g obsidian-headless

Authentication

Log in

ob login

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

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.

To log out and clear stored credentials:

ob logout

Environment variable

For non-interactive use (CI, scripts, servers), set the OBSIDIAN_AUTH_TOKEN environment variable instead of using ob login:

export OBSIDIAN_AUTH_TOKEN="your-auth-token"

When set, all commands that require authentication use this token automatically.

Services