Complete Headless Publish reference

Open beta Paid public-service gates

Headless Publish requires Node.js 22+, an active Obsidian Publish subscription, and approved interactive authentication. Listing and dry-run are evidence surfaces; site creation, setup, scope/options changes, unlink, and publication are mutations requiring exact approval. It uses the standalone ob command, not the desktop-app obsidian CLI.

Release rule

Before any authorized publication, preserve the immutable source commit/hash and exact include set, run and review a dry-run, and record approval for the exact account alias, site, path, scope, cost, and rollback owner. After publication, read back the exact public URL and expected content/hashes. A successful command is not public proof.

Commands

ob publish-list-sites

Read-only inventory of Publish sites available to the authenticated account. Account authentication remains separately gated. No options.

ob publish-create-site

Creates a Publish site. The required --slug names the URL identifier. This is a paid/public service mutation and requires exact approval.

ob publish-setup

Connects a local vault path to a Publish site. Optional options:

Option	Meaning
--site	Site ID or slug
--path	Local vault path; current directory when omitted

Setup requires exact target approval and rollback ownership.

ob publish

By default, Publish includes files with publish: true frontmatter.

Option	Meaning and safety
--path	Local vault path
--all	Includes all files, broadening scope beyond the frontmatter selection
--dry-run	Shows changes without publishing; preview only
--yes	Suppresses confirmation

Dry-run is the required pre-publication evidence surface. --all, --yes, or any actual public publication requires separately named approval.

ob publish-config

Run without setting options to read current include/exclude configuration. Setting options mutates publication scope.

Option	Meaning
--path	Local vault path
--includes	Comma-separated included folders; empty clears
--excludes	Comma-separated excluded folders; empty clears

ob publish-site-options

Run without setting options to read site display/navigation settings. Any setting option mutates the public site and requires exact approval plus public readback.

Option	Meaning
--path	Local vault path
--site-name	Site name
--index-file	Home page file path
--logo	Logo path; empty clears
--show-navigation	Navigation sidebar visibility
--show-graph	Graph visibility
--show-outline	Table of contents visibility
--show-search	Search visibility
--show-backlinks	Backlinks visibility
--show-hover-preview	Hover-preview visibility
--show-theme-toggle	Theme-toggle visibility
--default-theme	light or dark
--readable-line-length	Readable line-length setting
--strict-line-breaks	Strict line-break setting
--hide-title	Inline-title visibility
--sliding-window	Sliding-window mode
--nav-order	Comma-separated navigation paths; empty clears
--nav-hidden	Comma-separated hidden navigation paths; empty clears

ob publish-unlink

Disconnects a vault from a Publish site. Supports optional --path. Exact approval and a rollback plan are required.

Recovery

On wrong scope or content, stop further publication, preserve the dry-run/source/public readback, restore the prior approved source state, run a new reviewed dry-run, and republish or remove content only under exact approval. See Recovery.

Source

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