Desktop CLI or Headless?

Choose before you automate

Obsidian exposes three different terminal-adjacent surfaces. Choose by runtime and capability, not by command name alone.

Surface	Runtime	Supported purpose	Do not infer
Desktop obsidian	Obsidian desktop; both displayed app and installer versions must be 1.12.7+	The documented 115-command catalog: notes, files, metadata, plugins, themes, workspaces, local/Sync history, Publish status, UI and developer tools	That every third-party plugin action is stable or safe
Headless ob	Standalone open-beta client on Node.js 22+	Obsidian Sync and Publish without desktop Obsidian	Note-edit, search, property, task, metadata-cache, command-palette, plugin-graph, DOM, CDP, UI, or eval APIs
obsidian:// URI	An application or OS opens a URI	Open or create notes and trigger supported URI actions	A general shell or Headless API

Decision path

1. Need to query or control the running desktop app, its vault metadata, plugins, UI, history, or developer tools? Use obsidian.
2. Need to project files through Obsidian Sync or Publish on a server without desktop Obsidian? Use ob.
3. Need a link another application can open? Use obsidian://.
4. Need a Headless operation outside Sync or Publish? Stop. The accepted first-party sources do not document it.

Desktop gate

Before following a desktop runbook:

• In Settings -> General, verify both displayed app and installer values are 1.12.7 or later.
• Enable Command line interface and complete platform registration.
• Use obsidian [vault-selector] <command> [parameters] [flags].
• Put vault=<name-or-id> immediately after obsidian and before the command.
• Use key=value parameters, bare boolean flags, and the global --copy switch.
• The first command launches Obsidian when it is not already running.

Example:

obsidian vault="Project Notes" search query="release checklist" --copy

Headless gate

Before following a Headless runbook:

• Provide a separate Node.js 22+ runtime. This docs site builds on Node 20.x; that does not satisfy Headless.
• Install obsidian-headless and verify ob resolves on PATH.
• Stop for exact approval before authentication, account changes, logout, paid-service changes, remote-object creation, setup/unlink, mode or scope changes, continuous Sync, or publication.
• Authenticate only through the interactive prompt by running ob login with credential-bearing options omitted.
• Never place email, password, MFA, token, encryption-password, recovery-code, session-cookie, or secret values in commands, files, logs, CI, chat, prompts, screenshots, or receipts.

Capability and authority boundary

Headless Sync and Publish are transports or projections. They do not become Agent HQ, an accepted Score, project decision authority, or trusted-wiki Gold. External tools may edit synchronized Markdown under a separately approved writer policy, but that is filesystem work, not an ob note-edit or plugin API.

Never copy a live writable SQLite database between devices. Move information through supported application-level sync, supported exports, immutable receipts, Git objects, or an explicitly approved quiesced backup workflow.

Recovery truth

Desktop Obsidian documents local File Recovery and Sync history/read/restore commands. Headless documents status and inventory, but no Headless history, exact-version read, or restore command. A safe Headless workflow therefore needs a recoverable backup, source and destination status, second-device exact file/content/hash readback, conflict/deletion checks, and a named rollback owner. ob sync-status alone is not convergence proof.

Sources

First-party behavior was retrieved 2026-08-29 EDT:

• Obsidian CLI
• Obsidian Headless
• Headless Sync
• Headless Publish
• Updates and installer versions

See the dated source ledger for provenance and uncertainty notes.