wiki-cli: Default Transport Layer

Maz Works Knowledge Vault standardizes on the Obsidian CLI (shipped with Obsidian 1.12) as the preferred transport for vault mutations on desktop. This skill is the recipe reference for using it.

Substrate preference (v1.7+): This skill is a self-contained fallback. Prefer kepano/obsidian-skills (by Steph Ango, Obsidian CEO) as the authoritative substrate — its obsidian-cli skill is the canonical CLI reference for any Agent Skills runtime. If that separate skill is available, use it. The recipes below keep Maz Works Knowledge Vault functional when kepano's marketplace is not installed. Install kepano: claude plugin marketplace add kepano/obsidian-skills.

Why CLI over MCP

CLI loses to MCP on exactly one axis: it only works on machines where Obsidian itself is installed. For headless servers and mobile, fall through to the next transport in the chain.

Detection

At session start (or vault setup), run:

bash scripts/detect-transport.sh

This writes .vault-meta/transport.json with the schema:

{
  "preferred": "cli",
  "fallback_chain": ["cli", "filesystem"],
  "available": {
    "cli": {"present": true, "binary": "obsidian-cli", "version_string": "..."},
    "filesystem": {"present": true},
    "mcp_obsidian": {"present": null, "detection": "deferred"},
    "mcpvault": {"present": null, "detection": "deferred"}
  }
}

Read this file before any non-trivial vault mutation. Skills that need to read or write should consult preferred and pick the corresponding transport. The decision tree lives at wiki/references/transport-fallback.md.

Refresh detection with --force after installing/removing the Obsidian CLI:

bash scripts/detect-transport.sh --force

Recipes (CLI-first; fallback noted inline)

Each recipe shows the CLI form first. If the CLI is unavailable per the detection snapshot, fall through to the noted fallback. Variable substitution: $VAULT is the absolute vault root; $NOTE is a vault-relative path like wiki/concepts/Foo.md.

Read a note

# CLI
obsidian-cli read "$VAULT" "$NOTE"

# Fallback: Claude's Read tool with absolute path
# Read $VAULT/$NOTE

Create or overwrite a note

# CLI
obsidian-cli write "$VAULT" "$NOTE" < /path/to/content.md

# Fallback: Claude's Write tool with absolute path
# Write $VAULT/$NOTE with the desired content string

Append to a note

# CLI
echo "additional content" | obsidian-cli append "$VAULT" "$NOTE"

# Fallback: Read $VAULT/$NOTE, append manually, Write back

Search note content (CLI uses Obsidian's own search ranking)

# CLI
obsidian-cli search "$VAULT" "<query>"

# Fallback: ripgrep
rg --type=md "<query>" "$VAULT/wiki/"

Today's daily note (if Daily Notes plugin is enabled)

# CLI
obsidian-cli daily:today "$VAULT"
obsidian-cli daily:append "$VAULT" "captured at $(date)"

# Fallback: compute path manually
NOTE="$VAULT/wiki/daily/$(date +%Y-%m-%d).md"

Patch a frontmatter property

# CLI
obsidian-cli property:set "$VAULT" "$NOTE" status "evergreen"

# Fallback: read frontmatter, parse, mutate, rewrite (use mcp__obsidian-vault__update_frontmatter if MCP is configured)

List backlinks for a page

# CLI
obsidian-cli backlinks "$VAULT" "$NOTE"

# Fallback: ripgrep for wikilink references
rg --type=md "\[\[$(basename "$NOTE" .md)" "$VAULT/wiki/"

Open a Bases (.base) file's resolved view

# CLI
obsidian-cli bases "$VAULT" "$NOTE"
# (returns the resolved row list; supplements obsidian-bases skill which handles the .base file's YAML)

# Fallback: read the .base file directly; no resolved-view available without Obsidian itself

Tags + bookmarks

obsidian-cli tags "$VAULT"
obsidian-cli bookmarks "$VAULT"

When CLI is NOT the right choice

• Mobile (iOS Share extension): filesystem write into .raw/ is the only path; CLI is desktop-only.
• CI / headless ingest jobs: filesystem with manual frontmatter parsing.
• Cross-vault operations: CLI binds to one vault root per invocation; for federation, fall back to filesystem walks.
• Live edits while Obsidian is mid-save: rare race; CLI handles it correctly but in pathological cases the v1.7 wiki-lock.sh advisory locks (see skills/wiki-fold/ and agents/wiki-ingest.md) should be acquired first.

Cross-reference

• Decision tree: wiki/references/transport-fallback.md
• Legacy MCP options (A/B/C/D): skills/wiki/references/mcp-setup.md
• Concurrency policy (v1.7+): skills/wiki-ingest/SKILL.md §Concurrency
• Detection script: scripts/detect-transport.sh

How to think (10-principle mapping)

When working on this skill, apply the 10-principle loop. See skills/think/SKILL.md for the canonical framework.