Obsidian CLI & Headless

Obsidian provides two command-line tools for automation and scripting:

Obsidian CLI

Controls the running Obsidian desktop app from your terminal. Everything you can do in the app, you can do from the command line.

Obsidian Headless

A standalone client that runs independently of the desktop app. Sync vaults and publish sites from any server or CI environment.

Obsidian CLI

Obsidian CLI lets you control Obsidian from your terminal for scripting, automation, and integration with external tools — including developer commands to inspect elements, take screenshots, reload plugins, and run JavaScript in the app console.

Obsidian CLI requires the Obsidian 1.12.4 installer or later. See the installer version update guide in Obsidian’s update settings.

Install Obsidian CLI

Update Obsidian

Upgrade to the latest Obsidian installer version (1.12.4 or above).

Enable the CLI in settings

Go to Settings → General and enable Command line interface.

Follow the prompt to register Obsidian CLI. This adds obsidian to your system PATH.

The Obsidian app must be running for CLI commands to work. If it’s not running, the first command you execute will launch Obsidian automatically.

Run commands

Run a single command directly from your terminal:

# Get help
obsidian help

# Show Obsidian version
obsidian version

Or open the interactive terminal user interface (TUI) by entering obsidian with no arguments. The TUI supports autocomplete, command history, and reverse search (Ctrl+R):

# Open the TUI, then run a command without the "obsidian" prefix
obsidian
help

Parameters and flags

Commands accept parameters (key-value pairs) and flags (boolean switches):

# Parameter: name=value (quote values with spaces)
obsidian create name=Note content="Hello world"

# Flags: include the flag name to enable it
obsidian create name=Note content="Hello" open overwrite

# Multiline content: use \n for newlines
obsidian create name=Note content="# Title\n\nBody text"

Target a vault

If your terminal’s current working directory is inside a vault, that vault is used automatically. Otherwise, the currently active vault is used. To target a specific vault explicitly:

obsidian vault=Notes daily
obsidian vault="My Vault" search query="meeting notes"

Everyday examples

# Open today's daily note
obsidian daily

# Add a task to your daily note
obsidian daily:append content="- [ ] Buy groceries"

# Search your vault
obsidian search query="meeting notes"

# Read the active file
obsidian read

# Create a new note from a template
obsidian create name="Trip to Paris" template=Travel

# List all tags with counts
obsidian tags counts

# Copy the output of any command to clipboard
obsidian read --copy

Developer examples

# Open developer tools
obsidian devtools

# Reload a plugin you're developing
obsidian plugin:reload id=my-plugin

# Take a screenshot
obsidian dev:screenshot path=screenshot.png

# Execute JavaScript in the app
obsidian eval code="app.vault.getFiles().length"

Key command categories

Files and folders

Command	Description
`open file=<name>`	Open a file.
`read`	Read the active (or specified) file’s contents.
`create name=<name>`	Create a new file.
`append content=<text>`	Append content to a file.
`prepend content=<text>`	Prepend content after frontmatter.
`move to=<path>`	Move or rename a file.
`rename name=<name>`	Rename a file.
`delete`	Delete the active file.
`files`	List files in the vault.

Daily notes

Command	Description
`daily`	Open today’s daily note.
`daily:append content=<text>`	Append content to the daily note.
`daily:prepend content=<text>`	Prepend content to the daily note.
`daily:read`	Read the daily note.
`daily:path`	Get the expected path of today’s daily note.

Command	Description
`search query=<text>`	Search the vault. Returns matching file paths.
`search:context query=<text>`	Search with surrounding line context (grep-style output).

Plugins and themes

Command	Description
`plugins`	List installed plugins.
`plugin:enable id=<id>`	Enable a plugin.
`plugin:disable id=<id>`	Disable a plugin.
`plugin:install id=<id>`	Install a community plugin.
`plugin:reload id=<id>`	Reload a plugin (for development).
`themes`	List installed themes.
`theme:set name=<name>`	Activate a theme.
`snippet:enable name=<name>`	Enable a CSS snippet.
`snippet:disable name=<name>`	Disable a CSS snippet.

Workspace and tabs

Command	Description
`workspace`	Show the workspace tree.
`workspaces`	List saved workspaces.
`workspace:save name=<name>`	Save the current layout.
`workspace:load name=<name>`	Load a saved layout.
`tabs`	List open tabs.
`recents`	List recently opened files.

Tasks

Command	Description
`tasks`	List tasks in the vault.
`tasks todo`	List incomplete tasks.
`tasks daily`	List tasks from today’s daily note.
`task ref=<path:line> toggle`	Toggle a task’s completion status.

Bases

Command	Description
`bases`	List all `.base` files in the vault.
`base:views`	List views in the current base file.
`base:create`	Create a new item in a base.
`base:query`	Query a base and return results.

Bookmarks

Command	Description
`bookmarks`	List bookmarks.
`bookmark`	Add a bookmark (file, folder, search, or URL).

Links

Command	Description
`backlinks`	List backlinks to a file.
`links`	List outgoing links from a file.
`unresolved`	List unresolved links in the vault.
`orphans`	List files with no incoming links.
`deadends`	List files with no outgoing links.

Properties

Command	Description
`properties`	List properties in the vault or a specific file.
`property:set name=<name> value=<value>`	Set a property on a file.
`property:remove name=<name>`	Remove a property from a file.
`property:read name=<name>`	Read a property value from a file.
`aliases`	List aliases in the vault.

Sync commands (in-app)

These commands control Sync within the running Obsidian app. To sync without the desktop app, see Obsidian Headless.

Command	Description
`sync on` / `sync off`	Resume or pause sync.
`sync:status`	Show sync status and storage usage.
`sync:history`	List sync version history for a file.
`sync:read version=<n>`	Read a specific sync version.
`sync:restore version=<n>`	Restore a sync version.
`sync:deleted`	List deleted files in sync.

Publish commands (in-app)

Command	Description
`publish:site`	Show publish site info (slug, URL).
`publish:list`	List published files.
`publish:status`	List publish changes (new, changed, deleted).
`publish:add`	Publish the active file or all changed files.
`publish:remove`	Unpublish a file.
`publish:open`	Open the active file on the published site.

Tags and tasks

Command	Description
`tags`	List tags in the vault.
`tag name=<tag>`	Get tag info.
`tasks`	List tasks in the vault.
`task ref=<path:line> toggle`	Toggle a task’s completion status.

Vault

Command	Description
`vault`	Show vault info.
`vaults`	List known vaults.
`vault:open name=<name>`	Switch to a different vault (TUI only).
`wordcount`	Count words and characters.
`outline`	Show headings for the current file.
`random`	Open a random note.
`unique`	Create a unique note.

Developer commands

Command	Description
`devtools`	Toggle Electron developer tools.
`dev:screenshot path=<file>`	Take a screenshot (returns base64 PNG).
`dev:errors`	Show captured JavaScript errors.
`dev:console`	Show captured console messages.
`dev:css selector=<css>`	Inspect CSS with source locations.
`dev:dom selector=<css>`	Query DOM elements.
`eval code=<javascript>`	Execute JavaScript and return the result.

TUI keyboard shortcuts

Navigation

Action	Shortcut
Move cursor left	`←` / `Ctrl+B`
Move cursor right	`→` / `Ctrl+F`
Jump to start of line	`Ctrl+A`
Jump to end of line	`Ctrl+E`
Move back one word	`Alt+B`
Move forward one word	`Alt+F`

Editing

Action	Shortcut
Delete to start of line	`Ctrl+U`
Delete to end of line	`Ctrl+K`
Delete previous word	`Ctrl+W` / `Alt+Backspace`

Autocomplete

Action	Shortcut
Enter suggestion mode / accept suggestion	`Tab`
Exit suggestion mode	`Shift+Tab`
Enter suggestion mode (from fresh input)	`↓`

History

Action	Shortcut
Previous history entry	`↑` / `Ctrl+P`
Next history entry	`↓` / `Ctrl+N`
Reverse history search	`Ctrl+R`

Other

Action	Shortcut
Clear screen	`Ctrl+L`
Exit	`Ctrl+C` / `Ctrl+D`

Troubleshooting

Windows

Obsidian CLI on Windows requires the 1.12.4+ installer. When you install Obsidian 1.12.4+, the Obsidian.com terminal redirector is added in the folder where you installed the Obsidian.exe file. This redirector connects Obsidian’s GUI process to stdin/stdout, which is necessary because Obsidian normally runs as a GUI app incompatible with terminal output on Windows.

macOS

CLI registration adds the Obsidian binary to your PATH via ~/.zprofile. If the obsidian command isn’t found, check that this line exists in ~/.zprofile:

export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS"

For other shells (bash, fish), add the same path to ~/.bash_profile or run fish_add_path /Applications/Obsidian.app/Contents/MacOS.

Linux (AppImage)

Registration creates a symlink at /usr/local/bin/obsidian. Verify it exists:

ls -l /usr/local/bin/obsidian

If missing, create it manually:

sudo ln -s /path/to/obsidian /usr/local/bin/obsidian

If the symlink was placed in ~/.local/bin/ instead, ensure that directory is in your PATH.

Linux (Snap)

If the CLI doesn’t detect the insider .asar, set XDG_CONFIG_HOME to point to the Snap config path:

export XDG_CONFIG_HOME="$HOME/snap/obsidian/current/.config"

Add this to ~/.bashrc or ~/.zshrc to make it persistent.

Linux (Flatpak)

Create a symlink to the Flatpak binary:

# System install
ln -s /var/lib/flatpak/exports/bin/md.obsidian.Obsidian ~/.local/bin/obsidian

# User install
ln -s ~/.local/share/flatpak/exports/bin/md.obsidian.Obsidian ~/.local/bin/obsidian

Obsidian Headless

Obsidian Headless (open beta) is a standalone command-line client for Obsidian services. It runs without the desktop app, making it ideal for servers, CI pipelines, and automation workflows. Common use cases:

Automate remote backups
Publish a website on a schedule
Sync a shared vault to a server for other tools to consume
Give agentic tools vault access without exposing your full desktop

Obsidian Headless syncs and publishes vaults. It does not control the Obsidian desktop app. For controlling the running desktop app, use Obsidian CLI above.

Install Obsidian Headless

Obsidian Headless requires Node.js 22 or later.

npm install -g obsidian-headless

Authenticate

# Log in to your Obsidian account
ob login

# Log in with explicit credentials
ob login --email [email protected] --password yourpassword

# Log out and clear stored credentials
ob logout

All options are interactive when omitted — email and password are prompted, and two-factor authentication is requested automatically if enabled on your account.

Available services

Service	Description
Headless Sync	Sync vaults using Obsidian Sync, without the desktop app.
Headless Publish	Publish sites using Obsidian Publish, without the desktop app.

Core Plugins

Bases

User Interface

Extending Obsidian

Obsidian CLI & Headless

Obsidian CLI

Obsidian Headless

Obsidian CLI

Install Obsidian CLI

Run commands

Parameters and flags

Target a vault

Everyday examples

Developer examples

Key command categories

TUI keyboard shortcuts

Troubleshooting

Obsidian Headless

Install Obsidian Headless

Authenticate

Available services

Build docs developers (and LLMs) love

Core Plugins

Bases

User Interface

Extending Obsidian

Obsidian CLI

Obsidian Headless

​Obsidian CLI

​Install Obsidian CLI

​Run commands

​Parameters and flags

​Target a vault

​Everyday examples

​Developer examples

​Key command categories

​TUI keyboard shortcuts

​Troubleshooting

​Obsidian Headless

​Install Obsidian Headless

​Authenticate

​Available services

Build docs developers (and LLMs) love

Obsidian CLI

Install Obsidian CLI

Run commands

Parameters and flags

Target a vault

Everyday examples

Developer examples

Key command categories

TUI keyboard shortcuts

Troubleshooting

Obsidian Headless

Install Obsidian Headless

Authenticate

Available services