Obsidian Cli

Obsidian CLI

Interact with an Obsidian vault via the official CLI. Obsidian must be running (CLI communicates via IPC).

Configuration

Run setup.sh to auto-detect your vault, or manually create ~/.config/obsidian-cli/config.yaml:

vault: "MyVault"
vault_path: "/absolute/path/to/vault/"
binary: "/path/to/obsidian"

Settings from ~/.config/obsidian-cli/config.yaml:

• vault — your vault name
• vault_path — path to vault on disk
• binary — path to Obsidian binary

DAILY_FMT:  YYYY-MM-DD.md
NOISE:      2>/dev/null | grep -v "Loading updated\|out of date\|obsidian.md/download"

Invocation pattern:

 vault=""  2>/dev/null | grep -v "Loading updated\|out of date\|obsidian.md/download"

> Warning: On some systems, obsidian may be aliased (e.g., to cd ~/obsidian). Always use the full binary path from your config — never bare obsidian.

All examples below use obs as shorthand for the full binary path + noise filter. In practice, expand to the full invocation pattern above using values from ~/.config/obsidian-cli/config.yaml.

File Resolution

Two modes:

• file= — resolves by name like wikilinks (no extension needed)
• path= — exact path from vault root (e.g., folder/note.md)

Quote values with spaces: name="My Note". Use \n for newlines, \t for tabs in content strings.

Visual Formatting

When writing note content (create, append, prepend), follow visual formatting rules in @visual-formatting.md. Key principle: Visuals > prose. Use diagrams, tables, and callouts over paragraphs.

Workflow Patterns

Daily Notes

Append findings/decisions to today's note:

obs vault="" daily:append content="## 📝 Notes\n\nKey finding here"

Read today's note (always read before appending to avoid duplication):

obs vault="" daily:read

Auto-summarize: When no content is specified, analyze the current conversation and summarize key information worth noting — decisions, architecture, findings, code changes.

Research Capture

Create a new research note:

obs vault="" create name="Topic Name" content="# Topic Name\n\n## 🎯 Summary\n\n..."

Append to existing note:

obs vault="" append file="Topic Name" content="\n## 📝 Additional Findings\n\n..."

Use templates for recurring types:

obs vault="" create name="Note" template="Research"

Task Management

List open tasks:

obs vault="" tasks todo format=md

Today's tasks only:

obs vault="" tasks todo daily

Toggle a task complete:

obs vault="" task file="Note" line=15 done

Completed tasks:

obs vault="" tasks done

Knowledge Graph

Find what links to a note:

obs vault="" backlinks file="Note" counts

Find orphaned notes (no incoming links):

obs vault="" orphans

Find dead-end notes (no outgoing links):

obs vault="" deadends

Find unresolved/broken links:

obs vault="" unresolved counts

Show outgoing links:

obs vault="" links file="Note"

Search & Retrieve

Search with context:

obs vault="" search:context query="search term" limit=10

Search within a folder:

obs vault="" search:context query="term" path="folder"

Get note outline (headings):

obs vault="" outline file="Note" format=tree

Read a specific note:

obs vault="" read file="Note Name"

Templates

List available templates:

obs vault="" templates

Read a template's content:

obs vault="" template:read name="Template Name"

Create note from template:

obs vault="" create name="New Note" template="Template Name"

Properties (Frontmatter)

Set a property:

obs vault="" property:set file="Note" name="status" value="in-progress"

Read a property:

obs vault="" property:read file="Note" name="status"

List all properties in vault:

obs vault="" properties counts sort=count

Quick Reference

| Action | Command | |--------|---------| | Read daily | daily:read | | Append to daily | daily:append content="..." | | Prepend to daily | daily:prepend content="..." | | Read note | read file="Name" | | Create note | create name="Name" content="..." | | Append to note | append file="Name" content="..." | | Prepend to note | prepend file="Name" content="..." | | Delete note | delete file="Name" | | Move note | move file="Name" to="folder/" | | Rename note | rename file="Name" name="New" | | Open note | open file="Name" | | Open daily | daily | | Search | search:context query="..." limit=10 | | Tasks (open) | tasks todo format=md | | Tasks (done) | tasks done | | Toggle task | task file="Name" line=N done | | Tags | tags counts sort=count | | Backlinks | backlinks file="Name" counts | | Orphans | orphans | | Outline | outline file="Name" | | Files | files folder="path" | | Folders | folders | | Templates | templates | | Properties | properties counts sort=count | | Set property | property:set file="Name" name="key" value="val" | | Bookmarks | bookmarks | | Recent files | recents | | Random note | random:read | | Vault info | vault |

All commands use obs vault="" prefix. See Configuration for setup.

Direct File Access

When the CLI causes issues (callout escaping, complex edits), read/edit vault files directly using the vault path from ~/.config/obsidian-cli/config.yaml.

Use Read/Edit tools on /.md instead of CLI when:

• Content contains callouts ([!danger], [!tip], etc.) — CLI escapes the !
• You need to edit existing content (not just append/prepend)
• You need precise line-level edits

Common Mistakes

| Mistake | Fix | |---------|-----| | Callouts via CLI content= | CLI auto-escapes ! → [\!danger] renders as raw text. Use Read/Edit tools on vault files directly for callout content | | Using bare obsidian command | May be aliased. Use full binary path from config | | Forgetting noise filter | Always pipe through grep -v (see invocation pattern in Configuration) | | Appending without reading first | Always daily:read or read before appending to avoid duplication | | Using path= when file= works | Use file= for name-based resolution, path= only for exact paths | | Not escaping content | Use \n for newlines, quote values with spaces | | Checkboxes inside callouts | Known bug — place checkboxes outside/below callouts | | \n in mermaid node labels | Obsidian renders literal \n. Use `` for line breaks in mermaid | | Bright colors in mermaid | Dark theme makes white text + saturated fills unreadable. See dark-theme palette in @visual-formatting.md | | Obsidian not running | CLI requires Obsidian to be running (IPC) |

Full CLI Reference

See @cli-reference.md for complete command documentation with all options.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jcgonzalez25
• Source: jcgonzalez25/obsidian-cli-agent
• License: MIT

Install and usage instructions live in the source repository linked above.