Obsidian CLI

Obsidian CLI

Audience: AI agents and terminal users automating Obsidian vault operations. Goal: Drive Obsidian from the command line safely and reproducibly — file CRUD, frontmatter properties, tasks, search, link analysis, Bases, plugins, workspaces.

MANDATORY: Before any file operation (create, append, prepend, move, rename, delete, template:insert), read references/commands.md to confirm exact parameter/flag names.

MANDATORY: Before any frontmatter change (property:set, property:remove), read references/properties.md for type rules and value formats.

MANDATORY: Before any search, link analysis, or base query, read references/queries.md.

Prerequisites

• Obsidian 1.12+ installed (obsidian version).
• CLI enabled in Settings -> General -> Command line interface.
• Obsidian app must be running — CLI connects to the live instance.
• On macOS the PATH should include the binary: export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS" in ~/.zprofile.

Core concepts

Two modes

1. Single command: obsidian <command> [params] [flags].
2. TUI: obsidian with no command enters an interactive shell with autocomplete and history. See references/commands.md for TUI keybindings.

Parameters vs flags

• Parameter takes a value: name=Note content="Hello world".
• Flag is a boolean switch with no value: open, overwrite, newtab, inline.
• Multiline content uses \n and \t. Values with spaces require quotes.

Vault targeting

• Default vault = current working directory if it is a vault; otherwise the active vault.
• Explicit: vault=<name> or vault=<id> as the FIRST parameter before the command.

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

File targeting

• file=<name> — wikilink-style (name only, no path/extension).
• path=<path> — exact path from vault root, e.g. Projects/idea.md.
• If neither provided, most commands default to the active file.

Copy output

Add --copy on any command to copy its output to the clipboard.

obsidian read --copy
obsidian search query="TODO" --copy

Decision tree: picking the right command

"I want to write content into a note"

"I want to change a note's metadata"

See references/properties.md for full type rules.

"I want to find something in the vault"

See references/queries.md for the full search/link/base matrix.

"I want to manage tasks"

"I want to work with the daily note"

Agent workflow patterns

Pattern: append learning to a study note

obsidian append path="100xDevBootcamp/03_Web3/SelfStudy/classes/SS-W01 - Blockchains.md" \
  content="\n## New Insight\nContent here..."

obsidian property:set name=status value=in-progress \
  path="100xDevBootcamp/03_Web3/SelfStudy/classes/SS-W01 - Blockchains.md"

Pattern: search before creating

# Check if a concept note already exists
obsidian search query="Program Derived Addresses" \
  path="100xDevBootcamp/03_Web3/SelfStudy"

# If no result, create it. If found, append to it.

Pattern: create a concept note on demand

obsidian create \
  path="100xDevBootcamp/03_Web3/SelfStudy/concepts/PDAs.md" \
  content="---\ntitle: PDAs\ntags:\n  - web3\n  - concept\nstatus: active\n---\n\n# Program Derived Addresses (PDAs)\n\n## Intuition\n..."

Pattern: daily study log

obsidian daily:append content="\n## Web3 Study Session\n- Studied: W01 - Blockchains\n- Key concepts: distributed ledger, transaction lifecycle\n- Next: W02 - Wallets"

Pattern: vault health check

obsidian orphans
obsidian unresolved verbose
obsidian deadends

Pattern: check study progress

obsidian files folder="100xDevBootcamp/03_Web3/SelfStudy" total
obsidian properties file="SS-W01 - Blockchains"
obsidian tasks path="100xDevBootcamp/03_Web3/SelfStudy"

Safety guidelines for agents

• Idempotency. For appends, consider searching first to avoid duplicate sections.
• Overwrite is destructive. Never pass the overwrite flag on create without user confirmation.
• Trash vs permanent. delete trashes by default; delete ... permanent skips trash. Prefer trash unless the user explicitly asks otherwise.
• Dry-run by reading first. Before property:set or prepend on unfamiliar files, run obsidian read or obsidian properties to confirm current state.
• Escape quotes in content. Shell-escape " and $ inside content="...".
• Active-file ambiguity. If the user did not specify a target and the active file is unexpected, prefer file= or path= explicitly.

Troubleshooting

CLI not found

which obsidian
cat ~/.zprofile | grep Obsidian
export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS"

Commands not executing

• Ensure Obsidian app is running — the CLI connects to the running instance.
• Restart the terminal after initial CLI registration.
• Check version: obsidian version (requires 1.12+).

File not found

• Use file= for wikilink-style resolution (name only).
• Use path= for exact vault-relative paths.
• Confirm existence: obsidian search query="filename".

Further references

• Obsidian CLI docs
• Obsidian Headless
• Headless Sync

For the headless client (separate tool, standalone sync without the desktop app), see the "Obsidian Headless" section in references/commands.md.