Obsidian cli
Reference for driving the native Obsidian command-line interface (v1.12+). Use whenever a wiki-master operation needs to read, search, link, tag, or edit notes in the vault via the `obsidian` CLI.From its SKILL.md
npx -y skills add ehartye/wiki-master --skill obsidian-cliAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.8 KB, as published. Nobody here has run it
Driving the Obsidian CLI
The vault is targeted by name: obsidian vault=<name> <command> .... wiki-master
resolves <name> from WIKI_MASTER_VAULT_NAME or the vault folder's basename, and
its filesystem path from WIKI_MASTER_VAULT, defaulting to ~/.wiki-master-vault
(this convention lives in scripts/lib/vault.mjs — the bundled scripts use it, so
node scripts/health.mjs and friends need no path argument). Start there rather than
searching the disk for the vault.
file= resolves by name (like wikilinks); path= is an exact vault-relative path.
Prefer the scripts/lib/vault.mjs wrapper from Node; use raw commands when acting
directly. obsidian vault info=path prints the vault's filesystem root — get it
once so Read/Grep can work on real paths.
Windows invocation — REQUIRED
Never run obsidian from the Bash tool. The two binaries are Obsidian's own
design, and the official docs explain why: "Windows uses a terminal redirector
that connects Obsidian to stdin/stdout properly. This is necessary because
Obsidian normally runs as a GUI app which is incompatible with terminal outputs
on Windows. When you install Obsidian 1.12.7+ the Obsidian.com terminal
redirector will be added in the folder where you installed the Obsidian.exe
file."
Windows PATHEXT orders .com before .exe, so PowerShell and Node's
execFileSync select the redirector. Git Bash does not apply PATHEXT, so a
bare obsidian there finds the GUI binary, which prints nothing and exits 0 —
measured as 2 bytes of stdout against the redirector's real answer. Use the
PowerShell tool or vault.mjs. A PreToolUse hook enforces this; the rule is
mechanical, so it needs no restating elsewhere.
Empty is not an answer
Obsidian publishes no exit-code contract and does not document how a command signals "no results" — neither the official reference nor kepano's first-party skill says. That gap, not tool unreliability, is why an empty result needs one cheap check before anything is decided on the strength of it.
Probe lazily, never upfront. Run nothing in advance: any command that returns
results has already proven the backend alive — from then on, trust empties too.
Only when a command returns empty and that emptiness is about to drive a
decision (report "not ingested", declare no backlinks, skip a page) run
obsidian search query="the" total — a live backend prints a number, which
means the empty was real; trust it and every later empty without re-probing.
An empty canary means the backend is dead. A session whose commands all return
hits never probes at all.
Two failure modes people assume and neither holds: the app not running cannot produce a silent empty — measured on Windows, a dead app exits 1 with "The CLI is unable to find Obsidian. Please make sure Obsidian is running and try again." (the docs claim the first command launches Obsidian; it does not — start it yourself) — and index-rebuild has never been observed to. Do not cite either as a reason to distrust a result.
Syntax and the live contract
- Parameters take
=; flags are bare.create name="My Note" content="Hello"vscreate name=Note open overwrite.\n/\tfor multiline content. vault=<name>must be the first parameter, before the command.format=is a parameter, not a flag, and its default varies per command —searchdefaults totext,backlinks/tags/propertiestotsv,base:querytojson. Never assume JSON; ask for it.obsidian helpoutranks the docs. Obsidian's own skill says it "is always up to date" — so when the published reference and the binary disagree, the binary wins. Checkobsidian help <command>before concluding a flag is gone.- Prior art worth comparing against: kepano (Obsidian's CEO) publishes a
first-party
obsidian-cliAgent Skill. Where it and this skill agree —totalfor counts,file=vspath=, vault-first ordering — the agreement is independent corroboration, not inheritance.
Read / search
obsidian read path=wiki/concepts/alpha.mdobsidian search query="tag:clippings neural" path=wiki limit=10 format=json- Scope to
path=wikiby default —raw/holds immutable source dumps (one clipping can be a 219k-word thesis) and belongs in results only when asked. - Probe cost before fetching:
obsidian search query="..." total(bytes: ~4). - Never default to
search:context— it returns every matching line from every file (measured 1.5MB wheresearch limit=10returned 497 bytes), andlimit=bounds files, not lines, so it cannot save you. Escalate tosearch:contextonly with bothpath=and a narrow query.
Links & graph
obsidian backlinks file=alpha counts— who links hereobsidian links file=alpha— outgoing linksobsidian unresolved verbose format=json— broken links WITH source files. The bare form returns targets only;verboseis the difference between a defect you can act on and a string you can't attribute. Several subcommands have lossy defaults with averboseescape — preferformat=json verbose.- Health metrics come from
scripts/health.mjs, not fromorphans/deadends. The CLI computes those verdicts with structural files' links (index.md links everything, so nothing ever looks orphaned) and offers no source-side exclusion. health.mjs builds the graph from the filesystem.
Typed properties (frontmatter)
obsidian property:set name=reviewed value=2026-07-15 type=date path=wiki/concepts/alpha.mdobsidian property:read name=reviewed path=...obsidian properties path=...— list a note's properties
Create / edit / move
obsidian create path=wiki/sources/foo.md content="..."obsidian append path=... content="..."obsidian move file=foo to=wiki/entities
Tags, tasks, templates, bases
obsidian tags counts·obsidian tag name=neural verboseobsidian base:query file=stale.base view=all format=jsonobsidian template:insert name=source-note
Escape hatches
obsidian command id=<id>— run any Obsidian command (obsidian commandsto list)obsidian eval code="<js>"— arbitrary JS in app context (last resort). This is remote code execution against the vault, and it sits in the same namespace as the read-only subcommands: a blanketobsidian *permission grant covers it. It belongs in its own permission decision, not folded in withsearchandread. The same applies todev:cdpanddev:debug.
If a command fails, surface the running-guard message from
scripts/lib/vault.mjs (assertRunning) — it fails loudly, so a command that
returns is a command that ran.