Invocation

Windows ships two entry points in the install directory, and only one is the CLI:

• Obsidian.com — the CLI redirector. Handles stdin/stdout properly. Use this.
• Obsidian.exe — the GUI binary. Answers simple commands, but exits 127 with no output and no side effect for any colon command that carries an argument (property:read name=…, daily:append content=…, plugins:enabled versions).

Git Bash resolves a bare obsidian by appending .exe first, so it would hit the wrong one. A wrapper fixes it permanently — ~/bin is already first on the Bash tool's PATH:

With that in place, plain obsidian <command> works from the Bash tool. If it ever goes missing, obsidian property:read name=title path="wiki/index.md" exits 127 — recreate the wrapper, or call "/c/Program Files/Obsidian/Obsidian.com" by full path.

Prefer the Bash tool for pipelines and exit codes. PowerShell also resolves to Obsidian.com correctly now, but still wraps native stderr in NativeCommandError.

Output is clean — no banner, no stderr noise, no leading blank line — so no filtering helper is needed. Wrap calls in timeout 25 if Obsidian may still be starting up.

Syntax

• Parameters take a value: content="hello world". Quote anything with spaces.
• Flags are bare switches: total, overwrite, counts, permanent, verbose.
• Use \n / \t inside content= for newlines and tabs.
• --copy on any command copies the output to the clipboard.
• Chinese arguments and output work correctly through the Bash tool.

File targeting

Most commands default to the active file in the UI when neither is given — never rely on that from an agent, always pass one:

• path=<vault-relative path> — exact, includes the extension: path="wiki/index.md"
• file=<name> — resolves like a wikilink (bare name, no folder, no .md); prints Error: File "X" not found. and still exits 0 if the name is ambiguous or missing

Vault targeting

With exactly one vault registered, vault= is optional. Pass vault="<vault name>" first as soon as a second vault exists — otherwise commands silently hit the most recently focused vault.

When to use the CLI vs Read/Edit/Grep

Reach for the CLI only when you need Obsidian's index or live app state. Everything else is faster and more precise with the built-in tools (each CLI call costs ~1–2s of IPC).

CLI wins — no built-in equivalent:

Built-in tools win:

• Reading a file at a known path → Read (offset/limit, no IPC cost)
• Any content edit → Edit. The CLI has no edit command — only append / prepend / create … overwrite.
• Regex search, or several lines of surrounding context → Grep (search:context gives one matching line each, index-aware but not regex)
• Non-markdown files, scripts, configs
• Anything that must still work when Obsidian is closed

Quick reference

Two gotchas that survive the fixed setup

• properties path=… format=json beats property:read when you want the whole frontmatter at once — arrays come back as arrays.
• property:set writes the value verbatim. value="[a, b]" becomes the literal string "[a, b]". Pass type=list|number|checkbox|date|datetime, or build the value in code with eval + processFrontMatter (below).

eval — the escape hatch

eval runs one line of JavaScript inside the app with app in scope, awaits a returned promise, and prints => <result>. It reaches everything the dedicated commands cannot — computed frontmatter, the raw link graph, plugin internals.

Constraints:

• Single expression, no top-level await. Chain .then(() => 'done') instead — the returned promise is awaited for you. A bare await fails with Error: await is only valid in async functions….
• Quote carefully: wrap code= in double quotes and use single quotes inside the JS.
• Multi-line scripts: write to the scratchpad and pass code="$(cat /path/script.js)", keeping the whole thing one expression.

Use property:set type=list for a simple literal list; reach for processFrontMatter when the value is computed, when several keys change at once, or when you need types property:set cannot express.

Do not run unattended

These change global state or interrupt the user's session — ask first: restart, reload, devtools, plugins:restrict, plugin:install / plugin:uninstall, theme:set / theme:install / theme:uninstall, sync on|off, sync:restore, history:restore, publish:add / publish:remove, delete … permanent, workspace:load.

delete without permanent goes to the vault trash and is recoverable.

Troubleshooting

Plugin / theme development

dev:errors is useful on its own for diagnosing a misbehaving community plugin — it reports live exceptions with stack traces.

Attribution

Derived from kepano/obsidian-skills (MIT, Copyright (c) 2026 Steph Ango). Modified in this repo; the upstream licence is included as LICENSE.