obsidian-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# Obsidian CLI

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

## Command reference

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

## ⛔ Invocation — on Windows, never bare `obsidian` from Bash

Obsidian ships **two** binaries: `Obsidian.com` (22 KB, **console** subsystem — the CLI
relay) and `Obsidian.exe` (225 MB, **GUI** subsystem — the Electron app). Windows resolves
a bare command through `PATHEXT`, which lists `.COM` first — but **Git Bash (MSYS2) ignores
`PATHEXT`**: it tries the exact name, then appends `.exe`, and never tries `.com`.

So bare `obsidian` in Git Bash runs the GUI binary, which has no console attached. **The
command still runs — you just never see the result.** Measured 2026-08-05 on an identical
3-create/3-delete burst:

| Shell + invocation | Lines printed |
|---|---|
| PowerShell, bare `obsidian` | 6/6 |
| Git Bash, `Obsidian.com` | 6/6 |
| Git Bash, bare `obsidian` | **0/6** (all six operations still succeeded) |

That matters because several CLI failure modes are visible *only* in stdout — losing it
makes a silent failure indistinguishable from success.

- **Windows + Bash:** call `Obsidian.com` (by full path if it is not on `PATH`).
- **Windows + PowerShell:** bare `obsidian` resolves to the `.com` correctly.
- **macOS / Linux:** there is no `.com` shim — bare `obsidian` is correct.

Examples below use `obsidian` for readability. On Windows read that as `Obsidian.com`; the
`obsidian-cli-guard` hook enforces it (rule 6, Windows-only).

## Syntax

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

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

**Flags** are boolean switches with no value:

```bash
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`

**Always prefer `path=` over `file=`** — it is unambiguous and doesn't depend on vault index state.

## Vault targeting

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

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

---

## CRITICAL: the 4000-byte cliff

**The total command line must stay under 4000 bytes.** At 4001+ the CLI fails **silently and completely**:

- exit code **0**
- no stdout, no stderr
- **zero bytes written**
- and the IPC socket then dies, so every later CLI call hangs or returns `unable to find Obsidian`

The budget covers the whole command — command name, `path=`, flags **and** `content=`. Verified by binary search on Obsidian 1.13.7: 4000 bytes writes, 4001 does not; and content that wrote fine at a short path failed when only the path grew by 62 bytes.

**Root cause:** the CLI's IPC layer calls `JSON.parse` on socket data without reassembling messages, so a payload split across pipe frames parses as a truncated fragment and throws. Upstream bug [forum 117325](https://forum.obsidian.md/t/cli-create-with-content-over-4-kb-crashes-the-main-process-with-a-json-parse-error/117325), filed Aug 2026, **open and unfixed as of 1.14.0**. There is **no stdin, no `-F`, and no `content=@file`** on any command — the [stdin request](https://forum.obsidian.md/t/support-stdin-pipe-for-obsidian-cli/112855) has had no staff response.

**Content SHAPE does not matter.** Colons, `[[wikilinks]]`, `[md](links)`, `- [ ]` checkboxes, em-dashes, curly quotes and full YAML frontmatter all write correctly. *(An earlier version of this skill claimed a `word:colon` / `[...]` parser bug causing exit 127. That was tested and is **false** — the real axis is size, not shape.)*

---

## Two-path decision — split on SIZE

### Path A — total command line comfortably under 4000 bytes

Any characters are fine. Budget ~3500 bytes for content to leave room for the path and flags.

```bash
obsidian create path="Folder/Note.md" content="# Title\nParagraph text" silent
obsidian create path="Folder/Note.md" content="# Updated\nNew content" silent overwrite
obsidian append path="Folder/Note.md" content="\n## New Section\nMore content"
```

### Path B — anything larger, or any content of unknown size ⭐ default

**Never inline a real note into the command.** Stage it as a file and have the eval read it — the eval argument then stays a fixed ~200 characters no matter how big the note is.

```bash
# 1. Write the content with the Write tool (zero shell escaping), then stage it INSIDE the vault
cp "/path/to/scratch/note.md" "$VAULT/_tmp.md"

# 2. Read by VAULT-RELATIVE path (keeps `C:/` out of the argument) and write via the Vault API
Obsidian.com eval code="(function(){ var t='Folder/Note.md'; app.vault.adapter.read('_tmp.md').then(function(c){ app.vault.create(t, c); }); return 'started'; })()"
# => started    (returns immediately; the write lands a moment later)

# 3. Clean up, then VERIFY BY CONTENT — not by exit code, not by byte count
rm -f "$VAULT/_tmp.md"
node -e "console.log(require('fs').readFileSync('<target>','utf8').includes('MARKER'))"
```

Swap `app.vault.create(t, c)` for `app.vault.modify(app.vault.getFileByPath(t), c)` to overwrite, or `app.vault.append(app.vault.getFileByPath(t), c)` to append.

Verified writing **17,000 bytes** this way at a size where `create content=` fails silently.

From hamchowderr/braynee, MIT.

More from hamchowderr/braynee