obsidian-headless
Sync and publish Obsidian vaults from the command line with Obsidian Headless (`ob`), without the desktop app
Install / Use
npx skills add obsidianmd/obsidian-skills --skill obsidian-headlessInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of obsidian-headless
obsidian-headless scores 89/100 on our quality scale, 1481st of 4,698 Development & Engineering skills we index (top 32%).
Its SKILL.md is 4.4 KB long, split into 7 sections with 2 code examples: a solid amount of guidance for an agent.
With 52,232 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 5 days ago, so obsidian-headless is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-14. Automated pattern scan on 2026-11-14. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
obsidian-headless compared with similar skills
All 4 of these similar skills score higher than obsidian-headless; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| obsidian-headless (this skill)by obsidianmd | 89 | 52.2k | 5d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install obsidian-headless?
- Run
npx skills add obsidianmd/obsidian-skills --skill obsidian-headless. The install tabs above show the steps for each supported agent. - Which AI agents does obsidian-headless work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is obsidian-headless safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is obsidian-headless still maintained?
- The repository was last updated 5 days ago, so obsidian-headless is actively maintained.
Skill content
View source on GitHubname: obsidian-headless
description: Sync and publish Obsidian vaults from the command line with Obsidian Headless (ob), without the desktop app. Use when the user wants to set up or run Obsidian Sync or Obsidian Publish on a server, in CI, or from a terminal, or change a vault's Sync or Publish settings.
Obsidian Headless
Use Obsidian Headless (ob) to run Obsidian Sync and Obsidian Publish from the command line. It doesn't need the desktop app, so it works on servers, in CI, and in sandboxes. It's in open beta. Docs: https://help.obsidian.md/headless
ob only syncs and publishes files. To read or change notes without the app, edit the files directly and follow the obsidian-markdown skill. To control a running desktop app, use the obsidian-cli skill.
Before using ob
Check availability with ob --help. If it is missing, explain that Obsidian Headless requires Node.js 22 or later and offer installation with npm install -g obsidian-headless. Run ob <command> --help for a command's options.
Sync and Publish each need an active subscription on the user's account.
Most commands accept --json for machine-readable output.
Log in
ob login prints the account when already logged in. Otherwise it prompts for email, password, and a 2FA code, so ask the user to run it in their own terminal. Don't ask for their password or pass it with --password. ob logout clears the stored credentials.
Vault paths
Commands act on the vault in the current directory, or the one given with --path. Pass --path so the target is explicit. Before a command that changes remote state, confirm the vault, site, and path from list or status output.
Sync
Don't use the desktop app's Sync and Headless Sync for the same vault on the same device, because they cause conflicts. Ask the user to back up the vault folder before the first sync.
ob sync-list-remote # remote vaults, including shared ones
ob sync-list-local # vaults set up on this machine
ob sync-setup --vault "Research" --path ~/vaults/research
ob sync --path ~/vaults/research # sync once
ob sync --path ~/vaults/research --continuous # keep syncing as files change
ob sync-status --path ~/vaults/research
ob sync-unlink --path ~/vaults/research # disconnect and remove stored credentials
--vault takes a remote vault's name or ID. For an end-to-end encrypted vault, sync-setup prompts for the encryption password, so let the user enter it. Set --device-name to label this machine in version history.
--continuous runs until stopped, so start it in the background or as a service.
ob sync-create-remote --name "Research" creates a remote vault. Add --encryption e2ee for end-to-end encryption or --encryption standard for managed encryption.
Sync settings
ob sync-config --path <vault> prints the vault's settings. Change them with:
--mode bidirectional|pull-only|mirror-remote.pull-onlyignores local changes andmirror-remotereverts them, so confirm before setting either.--conflict-strategy merge|conflict--excluded-folders "Archive,Templates"--file-types image,audio,video,pdf,unsupportedfor the attachment types to sync.--configsfor the settings categories to sync, e.g.app,appearance,core-plugin.--config-dirwhen the vault's configuration folder isn't.obsidian.
An empty string clears a list option, e.g. --excluded-folders "".
Publish
ob publish-list-sites
ob publish-setup --site my-notes --path ~/vaults/research
ob publish --path ~/vaults/research --dry-run
ob publish --path ~/vaults/research --yes
ob publish includes only notes with publish: true in their properties. --all includes every file, so use it only when the user asks. Run --dry-run first and show the user the changes. Without --yes, ob publish waits for confirmation, so pass --yes once the user approves or for an unattended job they set up.
ob publish-create-site --slug my-notes creates a site at publish.obsidian.md/my-notes.
Run these with no options to print the current settings:
ob publish-configsets folders to include or exclude with--includesand--excludes.ob publish-site-optionssets the site name, home page, navigation, theme, and other display options. Runob publish-site-options --helpfor the full list.
ob publish-unlink disconnects the vault from its site.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
