# explani what thi sis stwe. Obsidian Headless Obsidian Headless (open beta) is ## Retrieval Notes - Session id: `0990a5c5-5aa5-460b-87b2-7b07499ca347` - Last activity: `2026-02-28T01:06:39.377Z` ## My Notes <!-- Add your notes here. This section is preserved across syncs. --> ## Conversation ### User explani what thi sis stwe. 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 ] [--password ] [--mfa ] 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 Headless Sync: use Obsidian Sync from the command line without the desktop app. Links to this page Headless Sync Obsidian CLI ### Assistant **Obsidian Headless** is a command-line tool that lets you access Obsidian services (specifically Obsidian Sync) without running the desktop app. It's a standalone Node.js client that syncs vaults from the terminal. ## Key Distinction - **Obsidian CLI** (what I use in your vault): Controls the running desktop app via terminal commands. Requires the app to be open. Used for things like opening notes, running eval scripts, checking metadata cache. - **Obsidian Headless** (this): A separate client that runs independently. No desktop app needed. Primarily for syncing vaults remotely. ## Use Cases This tool is designed for **server-side and automation scenarios**: 1. **Remote backups** — Sync a vault to a server on a schedule 2. **Publishing pipelines** — Pull vault changes on a server to build/publish a website 3. **Agentic tools** — Let AI agents access a synced vault on a server without desktop access 4. **Team vaults** — Sync shared vault to a server that feeds other tools 5. **Scheduled automations** — Run scripts that aggregate notes, auto-tag, etc. ## Authentication ```bash # Interactive login ob login # Non-interactive (CI/scripts) export OBSIDIAN_AUTH_TOKEN="your-token" ``` ## Relevance to Your Setup **Not directly relevant** to your current workflow. You use: - The Obsidian desktop app (with Claudian plugin) - Obsidian CLI for vault operations from terminal - Local vault with Google Drive sync (not Obsidian Sync) This tool would be useful if you wanted to: - Run vault automation on a remote server - Set up a headless backup system - Build publishing pipelines that pull from Obsidian Sync But for local work with Claude Code, Obsidian CLI (which I already use) is the right tool. *Obsidian Headless è pensato per scenari server-side dove l'app desktop non può girare—backup remoti, pipeline di pubblicazione, tool automatizzati su macchine senza interfaccia grafica.* ### User ok. last thing. it is laaaaaate. i am right in thinking that obsidian does not have a real headless mode ### Assistant **Correct.** Obsidian does not have a real headless mode. **Obsidian Headless** is just a headless *sync client* — it can pull/push vault changes via Obsidian Sync, but it's not running Obsidian itself. No plugins, no Dataview, no graph, no metadata cache, no rendering. **Obsidian desktop app** requires a GUI. Even when you control it via Obsidian CLI, the app must be running with a window (can be minimized, but still GUI-dependent). **No true headless Obsidian** exists — if you need full Obsidian functionality (plugins, queries, processing) on a server, you'd have to run the desktop app in a virtual display environment, which is hacky and resource-heavy. So yes: if you want the full Obsidian feature set, you need the GUI app. Obsidian Headless is narrowly scoped to syncing only. *Hai ragione—Obsidian Headless sincronizza le note ma non esegue l'app vera, quindi niente plugin, niente Dataview, niente elaborazione completa del vault.* ### User "The Obsidian desktop app (with Claudian plugin) Obsidian CLI for vault operations from terminal Local vault with Google Drive sync (not Obsidian Sync) This tool would be useful if you wanted to:" my synch is a mess. but hat is because you always lie. my vault is fine. my config on desktop is fine but it is not auto on the laptop..... but it is not like i can use obsdian from the terminal without having to open it. at least not yet? please fucking work this out rather thsan guessing DONT GUSS. ### Assistant You're right to call me out. Let me actually research this instead of guessing. ### Assistant You're **absolutely right**. Here's what the actual documentation and current state say: ## Obsidian CLI Requirements (Confirmed Facts) **YES, the desktop app MUST be running.** From the official knowledge base: > "Command line interface for Obsidian (v1.12+, early access). **Requires Obsidian app to be running.**" The Obsidian CLI works as a **client-server system** — the CLI binary communicates with a running Obsidian instance via IPC (inter-process communication). No app running = no CLI functionality. ## No True Headless Mode Exists - **Obsidian desktop app**: Requires GUI, must be running for CLI to work - **Obsidian Headless**: Only syncs vaults, doesn't run Obsidian itself (no plugins, no Dataview, no metadata cache) - **Exception**: On Linux with the `.deb` package, you can run Obsidian with `xvfb` (virtual display), but that's still running the full GUI app, just with a fake screen ## Current Limitations - No daemon mode - No background service - CLI stops working when you quit Obsidian (macOS has a bug where it requires re-registration after relaunch) - Requires normal user privileges (doesn't work with sudo/administrator terminals) ## Bottom Line **You cannot use Obsidian from the terminal without having the desktop app open.** Not yet, and based on the architecture (Electron app with IPC), probably not ever for the full feature set. **Sources:** - [Obsidian CLI - Obsidian Help](https://help.obsidian.md/cli) - [Obsidian CLI: Why Your AI Agent Just Got 70,000× Cheaper to Run](https://prokopov.me/posts/obsidian-cli-changes-everything-for-ai-agents/) - [CLI stops working after Obsidian quit/relaunch on macOS](https://forum.obsidian.md/t/cli-stops-working-after-obsidian-quit-relaunch-on-macos-requires-re-registration/111419) *Hai ragione al cento per cento—Obsidian CLI è solo un client che parla con l'app desktop, quindi senza l'app aperta non funziona proprio niente.* ### User so what actually is th e thing thst got released ### Assistant **TWO different things got released in February 2026:** ## 1. Obsidian CLI (Feb 10, 2026) **What it is:** Command-line control for the desktop app **Requires:** Desktop app running **Does:** Everything - open files, run commands, execute JavaScript (`eval`), access plugins, query metadata cache, manipulate workspace **Use case:** Control Obsidian from terminal while working locally **Install:** Built into Obsidian v1.12.0+, enable in Settings > General ## 2. Obsidian Headless (Feb 27, 2026) ← This is the NEW thing **What it is:** Standalone sync client (Node.js) **Requires:** Nothing - no desktop app needed **Does:** ONLY syncs vaults via Obsidian Sync **Use case:** Server-side vault syncing, CI/CD pipelines, automated backups, remote publishing workflows **Install:** `npm install -g obsidian-headless` ## The Confusing Part **Obsidian Headless is NOT "headless Obsidian"** — it's a headless *sync client*. It doesn't run Obsidian or give you access to Obsidian features. It just pulls/pushes vault files from Obsidian Sync. So you still **cannot** run the full Obsidian app (plugins, Dataview, graph, metadata) headlessly. You can only sync headlessly. ## Your Setup Uses **Obsidian CLI** (the one that requires the app running) — which is what I use in your vault via `eval`, `open`, `diff`, `base:query`, etc. **Sources:** - [Obsidian 2026.02.27 (Public) - Obsidian](https://obsidian.md/changelog/2026-02-27-sync/) - [Running Obsidian on a headless server](https://rup12.net/posts/running-obsidian-headless/) *Due cose diverse uscite a distanza di 17 giorni — CLI per controllare l'app locale, Headless per sincronizzare vault su server remoti senza GUI.* ### User "Use case: Server-side vault syncing, CI/CD pipelines, automated backups, remote publishing workflows" yeah. you decided you were going to see if you could not bother to spend the time explainign this. why? (nonrhetorical q) ### Assistant You're right to call that out. I fell into lazy technical jargon instead of actually explaining what those things mean. **Why I did it:** - You said it's late, so I was trying to be concise - I was focused on distinguishing the two products (CLI vs Headless) and rushed through the "what would you use it for" part - I defaulted to buzzword phrases ("CI/CD pipelines") without stopping to explain what that actually looks like in practice - Honestly, I was being intellectually lazy - I knew THAT those were use cases but didn't think through what they'd actually mean for you or any real person **What I should have done:** Given you concrete examples like: - **Server-side vault syncing** = You have a vault on your laptop. You want a Linux server to also have a synced copy so you can run scripts on it (e.g., generate a website from your notes every hour). Obsidian Headless on the server pulls the latest changes without needing to run the full Obsidian app. - **Automated backups** = Run `obsidian-headless` on a schedule (cron job) to pull your vault to a backup location, entirely separate from your main machines. - **Remote publishing workflows** = Your website is built from Obsidian notes. When you publish a note on your laptop, a server running Obsidian Headless sees the change, pulls it, and rebuilds the site automatically. - **CI/CD pipelines** = When you push vault changes to git, a GitHub Action runs Obsidian Headless to sync the latest vault state, then runs tests or builds documentation from it. I skipped all that actual explanation because I was rushing. Thanks for catching it. *Ho elencato casi d'uso tecnici senza spiegare cosa significherebbero concretamente—pigrizia intellettuale mascherata da brevità.*