Obsidian CLI

Use the obsidian CLI to interact with a running Obsidian instance. Requires Obsidian to be open.

Mindset

The CLI is a thin bridge between the shell and a live Obsidian process — it sends commands to the running app rather than manipulating files directly. This means Obsidian's own logic (link resolution, template expansion, plugin hooks) runs as normal, making CLI operations safer and more consistent than direct file writes.

When to apply: Reading, creating, or searching notes from an agent workflow; interacting with daily notes or tasks programmatically; or developing and debugging Obsidian plugins from the command line. When NOT to apply: Obsidian is not open, the vault is remote or network-mounted, or the operation requires browser-level interaction not exposed by the CLI.

Command reference

Run obsidian help to see all available commands. This is always up to date. Full docs: help.obsidian.md/cli

Syntax

Parameters take a value with =. Quote values with spaces:

obsidian create name="My Note" content="Hello world"

Flags are boolean switches with no value:

obsidian create name="My Note" silent overwrite

For multiline content use \n for newline and \t for tab.

File targeting

Many commands accept file or path to target a file. Without either, the active file is used.

• file=<name> — resolves like a wikilink (name only, no path or extension needed)
• path=<path> — exact path from vault root, e.g. folder/note.md

Vault targeting

Commands target the most recently focused vault by default. Use vault=<name> as the first parameter to target a specific vault:

obsidian vault="My Vault" search query="test"

Common patterns

obsidian read file="My Note"
obsidian create name="New Note" content="# Hello" template="Template" silent
obsidian append file="My Note" content="New line"
obsidian search query="search term" limit=10
obsidian daily:read
obsidian daily:append content="- [ ] New task"
obsidian property:set name="status" value="done" file="My Note"
obsidian tasks daily todo
obsidian tags sort=count counts
obsidian backlinks file="My Note"

Use --copy on any command to copy output to clipboard. Use silent to prevent files from opening. Use total on list commands to get a count.

Plugin development

Develop/test cycle

After making code changes to a plugin or theme, follow this workflow:

1. Reload the plugin to pick up changes:

   obsidian plugin:reload id=my-plugin

2. Check for errors — if errors appear, fix and repeat from step 1:

   obsidian dev:errors

3. Verify visually with a screenshot or DOM inspection:

   obsidian dev:screenshot path=screenshot.png
   obsidian dev:dom selector=".workspace-leaf" text

4. Check console output for warnings or unexpected logs:

   obsidian dev:console level=error

Additional developer commands

Run JavaScript in the app context:

obsidian eval code="app.vault.getFiles().length"

Inspect CSS values:

obsidian dev:css selector=".workspace-leaf" prop=background-color

Toggle mobile emulation:

obsidian dev:mobile on

Run obsidian help to see additional developer commands including CDP and debugger controls.

Common Mistakes

1. Using path= when file= is sufficient

NEVER use path= when the note name is unique across the vault. path= requires the exact path from vault root including extension. file= resolves like a wikilink — name only, no path, no extension needed. Prefer file= unless you need to disambiguate files with the same name in different folders.

WHY: Using path= tightly couples commands to the vault's folder structure. If the file is ever moved, every command referencing it breaks silently or errors out.

# BAD — unnecessarily verbose, breaks if file moves
obsidian read path="folder/subfolder/My Note.md"

# GOOD — resolves by name, works regardless of location
obsidian read file="My Note"

2. Forgetting to quote parameter values that contain spaces

NEVER pass parameter values that contain spaces without surrounding quotes. Unquoted values are parsed as separate tokens and the command fails or targets the wrong file.

WHY: The CLI tokenises on whitespace, so file=Meeting Notes is read as file=Meeting with Notes treated as an unknown flag, causing silent misbehaviour or hard-to-diagnose errors.

# BAD — "Meeting" is parsed as the file name, "Notes" as a flag
obsidian read file=Meeting Notes

# GOOD — full name passed as a single value
obsidian read file="Meeting Notes"

3. Not using silent when creating or updating files

NEVER omit the silent flag when creating or updating files from an agent workflow. Without silent, Obsidian opens the created or updated file in the editor. When running CLI commands from an agent workflow, this disrupts the user's current view and focus.

WHY: Every file-write command without silent hijacks the user's editor pane, yanking them away from whatever they were doing and making automated multi-step workflows feel broken and intrusive.

# BAD — Obsidian opens the new file, pulling the user away from their work
obsidian create name="Draft" content="# Draft"

# GOOD — file is created without changing the editor state
obsidian create name="Draft" content="# Draft" silent

4. Using obsidian eval in production plugin code

NEVER embed obsidian eval calls in production plugin code. obsidian eval runs arbitrary JavaScript in the app context. It is a development and debugging tool only. Embedding eval calls in plugin code creates security risks and unpredictable behaviour.

WHY: obsidian eval bypasses normal plugin sandboxing. In production it exposes the full app context to arbitrary string execution, making the plugin a vector for code injection and violating Obsidian's plugin review guidelines.

# BAD — production plugin calling eval to inspect state
obsidian eval code="app.vault.getFiles().map(f => f.path)"

# GOOD — use eval only during development to inspect or prototype, then replace with proper plugin API calls
obsidian eval code="app.vault.getFiles().length"   # dev/debug only

5. Assuming the CLI targets the right vault when multiple vaults are open

NEVER omit vault=<name> when the user may have more than one vault open and vault identity matters. By default, commands target the most recently focused vault. When the user has two or more vaults open, this is unpredictable. Always specify vault=<name> as the first parameter when vault identity matters.

WHY: Focus can shift between vaults at any moment. Omitting vault= means writes or reads silently land in the wrong vault with no error, causing data to appear in unexpected places or tasks to be missed entirely.

# BAD — may silently write to the wrong vault if focus has shifted
obsidian daily:append content="- [ ] Review PR"

# GOOD — explicitly targets the intended vault
obsidian vault="Work" daily:append content="- [ ] Review PR"

References

• Obsidian CLI docs